mandoc -Tlint and Mdocdate

Post by Sebastien Marie
Hi,
With latest commits on mandoc (particulary mdoc_validate.c r1.252), I
have a problem with mandoc -Tlint regarding Dd macro.
Some days ago, I started to validate the man page of sysclean using
mandoc -Tlint.
sysclean is a tool designed for OpenBSD, and maintained externally in a
git repository.
.Dd June 18, 2017
.Dt SYSCLEAN 8
.Os

morning.

presumably because you have a blank Os field, mandoc will look
elesewhere and is concluding that this is openbsd. maybe you can use a
dummy value, but wait for ingo's reply, as he will better know the
criteria for Os matching, and what a good way to do this is.

note that this is just flagging this as "STYLE": the old style Dd does
work (hence just ignoring the message may be the best choice). but it's
not "not respecting the specification".

jmc

Post by Sebastien Marie
Document preamble and NAME section macros
Dd document date: $Mdocdate$ | month day, year
Dt document title: TITLE section [arch]
Os operating system version: [system [version]]
But mandoc -Tlint complains about missing Mdocdate.
$ mandoc -Tlint sysclean.8
mandoc: sysclean.8:17:5: STYLE: Mdocdate missing: Dd June
The current check requires Dd to be in "Mdocdate" format if the Os is
OpenBSD. It seems to me it doesn't respect the specification, which
allow Dd to be a plain date (month day, year).
Due to the fact I am not using CVS for this project, I couldn't use
$Mdocdate$ keyword (and have the date isn't automatically filled).
Alternatively, I could maintain manually Dd as "$Mdocdate: month day year $",
but it seems a limitation for me, so I prefer reported it.
Thanks.
--
Sebastien Marie

Jeremie Courreges-Anglas

2017-06-21 09:39:53 UTC

This post might be inappropriate. Click to display it.

Sebastien Marie

2017-06-21 10:26:14 UTC

Post by Sebastien Marie
But mandoc -Tlint complains about missing Mdocdate.
$ mandoc -Tlint sysclean.8
mandoc: sysclean.8:17:5: STYLE: Mdocdate missing: Dd June

With another project, I get this warning about Dd, plus a message about
a missing RCS Id.

ah, I don't have this one. But after checking, my man page has a
$OpenBSD$ tag inside it... it should come from the mdoc.template I used
to start writing the file. :)

If I remove it, I have the same STYLE warning.

Post by Sebastien Marie
Alternatively, I could maintain manually Dd as "$Mdocdate: month day year $",
but it seems a limitation for me, so I prefer reported it.

I can just ignore those STYLE warnings. Using -Wwarning to get rid of
STYLE warnings would lose quite a useful tips, right?

According to mandoc man page, -Wwarning will avoid all styles warning.
Here the complete list (taken from mandoc.h):

MANDOCERR_MDOCDATE, /* Mdocdate found: Dd ... */
MANDOCERR_MDOCDATE_MISSING, /* Mdocdate missing: Dd ... */
MANDOCERR_DATE_LEGACY, /* legacy man(7) date format: Dd ... */
MANDOCERR_RCS_MISSING, /* RCS id missing */
MANDOCERR_RCS_REP, /* duplicate RCS id: ... */
MANDOCERR_MACRO_USELESS, /* useless macro: macro */
MANDOCERR_BX, /* consider using OS macro: macro */
MANDOCERR_ER_ORDER, /* errnos out of order: Er ... */
MANDOCERR_ER_REP, /* duplicate errno: Er ... */
MANDOCERR_ND_DOT, /* description line ends with a full stop */
MANDOCERR_DELIM, /* no blank before trailing delimiter: macro ... */
MANDOCERR_FUNC, /* function name without markup: name() */

--
Sebastien Marie

Ingo Schwarze

2017-06-21 15:22:12 UTC

Hi Sebastien and Jeremie,

Post by Sebastien Marie

Post by Sebastien Marie
But mandoc -Tlint complains about missing Mdocdate.
$ mandoc -Tlint sysclean.8
mandoc: sysclean.8:17:5: STYLE: Mdocdate missing: Dd June

With another project, I get this warning about Dd, plus a message
about a missing RCS Id.

ah, I don't have this one. But after checking, my man page has a
$OpenBSD$ tag inside it... it should come from the mdoc.template I
used to start writing the file. :)
If I remove it, I have the same STYLE warning.

You currently have the following options:

1. Ignore the two style messages.
As jmc@ rightly observed, and as the mandoc(1) manual says
below DIAGNOSTICS, a style recommendation is not an error,
and style messages are occasionally false positives.
Both of these messages occur at most once per page.

Of course, having to ignore a message is not fully satisfactory,
and keeping false positives down to a minimum *is* among my
goals, even for style recommendations.

2. Put a dummy .\" $OpenBSD$ line and a manually maintained
.Dd $Mdocdate Month day year$ line into the file even though
your VCS won't expand it.

That is icky, working around an issue in a non-intuitive way
instead of solving the root cause, so i can't really recommend it.

3. Use "mandoc -Ios= -Tlint" for checking pages that are supposed
to be portable.

That is not fully satisfactory because it disables *all* operating
system specific style messages. It is likely that you do want to
follow OpenBSD style in general, just not those parts that apply
to the base system only.

4. Put something like ".Os ratpoison" into the manual page.

I clearly recommend against that. It not only suppers from
the same problem as option 3 of disabling more than intended;
it also results in an inconsistent user experience with the
bottom line of manual pages (admittedly a minor point, though).

5. Use "mandoc -Tlint -Wwarning" for these projects.

I clearly recommend against that. It disables even more than
option 3, namely, all style recommendations, most of which are
just as useful for portable projects as for base system manuals.

As there is no fully satisfactory option, i propose the patch below.
It add the "-W portable" command line option, which is a variant of
"-W style" hiding messages that only apply to base system manuals.

In general, i don't like adding knobs. But when the choice is
between having innocent people harassed with false positives and
between providing a knob for saying which checks you want, in a way
that is actually needed in practice, then i prefer the knob to the
harassment.

OK for the patch below?

Post by Sebastien Marie
According to mandoc man page, -Wwarning will avoid all styles warning.

The list of messages is also in the mandoc(1) manual, with an
explanation of each message.

Yours,
Ingo

Index: main.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/main.c,v
retrieving revision 1.195
diff -u -p -r1.195 main.c
--- main.c 3 Jun 2017 12:16:19 -0000 1.195
+++ main.c 21 Jun 2017 15:09:46 -0000
@@ -68,8 +68,8 @@ enum outt {

struct curparse {
struct mparse *mp;
- enum mandoclevel wlevel; /* ignore messages below this */
int wstop; /* stop after a file with a warning */
+ enum mandocerr mmin; /* ignore messages below this */
enum outt outtype; /* which output to use */
void *outdata; /* data for output */
struct manoutput *outopts; /* output options */
@@ -159,7 +159,7 @@ main(int argc, char *argv[])

memset(&curp, 0, sizeof(struct curparse));
curp.outtype = OUTT_LOCALE;
- curp.wlevel = MANDOCLEVEL_BADARG;
+ curp.mmin = MANDOCERR_MAX;
curp.outopts = &conf.output;
options = MPARSE_SO | MPARSE_UTF8 | MPARSE_LATIN1;
defos = NULL;
@@ -416,7 +416,7 @@ main(int argc, char *argv[])
moptions(&options, auxpaths);

mchars_alloc();
- curp.mp = mparse_alloc(options, curp.wlevel, mmsg, defos);
+ curp.mp = mparse_alloc(options, curp.mmin, mmsg, defos);

/*
* Conditionally start up the lookaside buffer before parsing.
@@ -907,7 +907,7 @@ toptions(struct curparse *curp, char *ar
curp->outtype = OUTT_ASCII;
else if (0 == strcmp(arg, "lint")) {
curp->outtype = OUTT_LINT;
- curp->wlevel = MANDOCLEVEL_STYLE;
+ curp->mmin = MANDOCERR_STYLE;
} else if (0 == strcmp(arg, "tree"))
curp->outtype = OUTT_TREE;
else if (0 == strcmp(arg, "man"))
@@ -936,16 +936,17 @@ static int
woptions(struct curparse *curp, char *arg)
{
char *v, *o;
- const char *toks[8];
+ const char *toks[9];

toks[0] = "stop";
toks[1] = "all";
toks[2] = "style";
- toks[3] = "warning";
- toks[4] = "error";
- toks[5] = "unsupp";
- toks[6] = "fatal";
- toks[7] = NULL;
+ toks[3] = "portable";
+ toks[4] = "warning";
+ toks[5] = "error";
+ toks[6] = "unsupp";
+ toks[7] = "fatal";
+ toks[8] = NULL;

while (*arg) {
o = arg;
@@ -955,19 +956,22 @@ woptions(struct curparse *curp, char *ar
break;
case 1:
case 2:
- curp->wlevel = MANDOCLEVEL_STYLE;
+ curp->mmin = MANDOCERR_STYLE;
break;
case 3:
- curp->wlevel = MANDOCLEVEL_WARNING;
+ curp->mmin = MANDOCERR_PORTABLE;
break;
case 4:
- curp->wlevel = MANDOCLEVEL_ERROR;
+ curp->mmin = MANDOCERR_WARNING;
break;
case 5:
- curp->wlevel = MANDOCLEVEL_UNSUPP;
+ curp->mmin = MANDOCERR_ERROR;
break;
case 6:
- curp->wlevel = MANDOCLEVEL_BADARG;
+ curp->mmin = MANDOCERR_UNSUPP;
+ break;
+ case 7:
+ curp->mmin = MANDOCERR_MAX;
break;
default:
warnx("-W %s: Bad argument", o);
Index: mandoc.1
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.1,v
retrieving revision 1.125
diff -u -p -r1.125 mandoc.1
--- mandoc.1 17 Jun 2017 23:06:43 -0000 1.125
+++ mandoc.1 21 Jun 2017 15:09:46 -0000
@@ -158,7 +158,12 @@ or
.Cm unsupp ;
.Cm all
is an alias for
-.Cm style .
+.Cm style ,
+and
+.Cm portable
+is a variant of
+.Cm style
+hiding style recommendations that only apply to base system manuals.
By default,
.Nm
is silent.
@@ -746,7 +751,7 @@ are hidden unless their level, or a lowe
option or
.Fl T Cm lint
output mode.
-.Ss Style messages
+.Pp
As indicated below, some style checks are only performed if a
specific operating system name occurs in the arguments of the
.Ic \&Os
@@ -756,6 +761,10 @@ command line option, or, if neither are
of the
.Xr uname 3
function.
+.Ss Style messages for base system manuals
+These are not shown if
+.Fl W Cm portable
+is specified.
.Bl -ohang
.It Sy "Mdocdate found"
.Pq mdoc , Nx
@@ -778,6 +787,17 @@ macro does not use CVS
keyword substitution, but using it is conventionally expected in the
.Ox
base system.
+.It Sy "RCS id missing"
+.Pq Ox , Nx
+The manual page lacks the comment line with the RCS identifier
+generated by CVS
+.Ic OpenBSD
+or
+.Ic NetBSD
+keyword substitution as conventionally used in these operating systems.
+.El
+.Ss Style messages for all manual pages
+.Bl -ohang
.It Sy "legacy man(7) date format"
.Pq mdoc
The
@@ -791,14 +811,6 @@ Consider using the conventional
date format
.Dq "Month dd, yyyy"
instead.
-.It Sy "RCS id missing"
-.Pq Ox , Nx
-The manual page lacks the comment line with the RCS identifier
-generated by CVS
-.Ic OpenBSD
-or
-.Ic NetBSD
-keyword substitution as conventionally used in these operating systems.
.It Sy "duplicate RCS id"
A single manual page contains two copies of the RCS identifier for
the same operating system.
Index: mandoc.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.h,v
retrieving revision 1.174
diff -u -p -r1.174 mandoc.h
--- mandoc.h 17 Jun 2017 23:06:43 -0000 1.174
+++ mandoc.h 21 Jun 2017 15:09:46 -0000
@@ -48,8 +48,11 @@ enum mandocerr {

MANDOCERR_MDOCDATE, /* Mdocdate found: Dd ... */
MANDOCERR_MDOCDATE_MISSING, /* Mdocdate missing: Dd ... */
- MANDOCERR_DATE_LEGACY, /* legacy man(7) date format: Dd ... */
MANDOCERR_RCS_MISSING, /* RCS id missing */
+
+ MANDOCERR_PORTABLE, /* ===== style hints for portable ===== */
+
+ MANDOCERR_DATE_LEGACY, /* legacy man(7) date format: Dd ... */
MANDOCERR_RCS_REP, /* duplicate RCS id: ... */
MANDOCERR_MACRO_USELESS, /* useless macro: macro */
MANDOCERR_BX, /* consider using OS macro: macro */
@@ -448,7 +451,7 @@ const char *mchars_uc2str(int);
int mchars_num2uc(const char *, size_t);
int mchars_spec2cp(const char *, size_t);
const char *mchars_spec2str(const char *, size_t, size_t *);
-struct mparse *mparse_alloc(int, enum mandoclevel, mandocmsg, const char *);
+struct mparse *mparse_alloc(int, enum mandocerr, mandocmsg, const char *);
void mparse_free(struct mparse *);
void mparse_keep(struct mparse *);
int mparse_open(struct mparse *, const char *);
Index: read.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/read.c,v
retrieving revision 1.150
diff -u -p -r1.150 read.c
--- read.c 17 Jun 2017 23:06:43 -0000 1.150
+++ read.c 21 Jun 2017 15:09:46 -0000
@@ -52,7 +52,7 @@ struct mparse {
const char *defos; /* default operating system */
mandocmsg mmsg; /* warning/error message handler */
enum mandoclevel file_status; /* status of current parse */
- enum mandoclevel wlevel; /* ignore messages below this */
+ enum mandocerr mmin; /* ignore messages below this */
int options; /* parser options */
int gzip; /* current input file is gzipped */
int filenc; /* encoding of the current file */
@@ -82,12 +82,15 @@ static const enum mandocerr mandoclimits
static const char * const mandocerrs[MANDOCERR_MAX] = {
"ok",

- "generic style suggestion",
+ "base system convention",

"Mdocdate found",
"Mdocdate missing",
- "legacy man(7) date format",
"RCS id missing",
+
+ "generic style suggestion",
+
+ "legacy man(7) date format",
"duplicate RCS id",
"useless macro",
"consider using OS macro",
@@ -738,7 +741,7 @@ mparse_open(struct mparse *curp, const c
}

struct mparse *
-mparse_alloc(int options, enum mandoclevel wlevel, mandocmsg mmsg,
+mparse_alloc(int options, enum mandocerr mmin, mandocmsg mmsg,
const char *defos)
{
struct mparse *curp;
@@ -746,7 +749,7 @@ mparse_alloc(int options, enum mandoclev
curp = mandoc_calloc(1, sizeof(struct mparse));

curp->options = options;
- curp->wlevel = wlevel;
+ curp->mmin = mmin;
curp->mmsg = mmsg;
curp->defos = defos;

@@ -838,12 +841,12 @@ mandoc_msg(enum mandocerr er, struct mpa
{
enum mandoclevel level;

+ if (er < m->mmin && er != MANDOCERR_FILE)
+ return;
+
level = MANDOCLEVEL_UNSUPP;
while (er < mandoclimits[level])
level--;
-
- if (level < m->wlevel && er != MANDOCERR_FILE)
- return;

if (m->mmsg)
(*m->mmsg)(er, level, m->file, ln, col, msg);

Jason McIntyre

2017-06-21 22:10:55 UTC

Post by Ingo Schwarze
Hi Sebastien and Jeremie,

Post by Sebastien Marie

Post by Sebastien Marie
But mandoc -Tlint complains about missing Mdocdate.
$ mandoc -Tlint sysclean.8
mandoc: sysclean.8:17:5: STYLE: Mdocdate missing: Dd June

With another project, I get this warning about Dd, plus a message
about a missing RCS Id.

ah, I don't have this one. But after checking, my man page has a
$OpenBSD$ tag inside it... it should come from the mdoc.template I
used to start writing the file. :)
If I remove it, I have the same STYLE warning.

1. Ignore the two style messages.
below DIAGNOSTICS, a style recommendation is not an error,
and style messages are occasionally false positives.
Both of these messages occur at most once per page.
Of course, having to ignore a message is not fully satisfactory,
and keeping false positives down to a minimum *is* among my
goals, even for style recommendations.
2. Put a dummy .\" $OpenBSD$ line and a manually maintained
.Dd $Mdocdate Month day year$ line into the file even though
your VCS won't expand it.
That is icky, working around an issue in a non-intuitive way
instead of solving the root cause, so i can't really recommend it.
3. Use "mandoc -Ios= -Tlint" for checking pages that are supposed
to be portable.
That is not fully satisfactory because it disables *all* operating
system specific style messages. It is likely that you do want to
follow OpenBSD style in general, just not those parts that apply
to the base system only.
4. Put something like ".Os ratpoison" into the manual page.
I clearly recommend against that. It not only suppers from
the same problem as option 3 of disabling more than intended;
it also results in an inconsistent user experience with the
bottom line of manual pages (admittedly a minor point, though).
5. Use "mandoc -Tlint -Wwarning" for these projects.
I clearly recommend against that. It disables even more than
option 3, namely, all style recommendations, most of which are
just as useful for portable projects as for base system manuals.
As there is no fully satisfactory option, i propose the patch below.
It add the "-W portable" command line option, which is a variant of
"-W style" hiding messages that only apply to base system manuals.

evening.

i'm not entirely convinced... are there likely to be other style
warnings that apply to our base manuals but not "portable"? if there's a
list of things then maybe it makes sense.

otherwise i wonder if we can;t try and make things clearer (style
warning is not a mistake) and leave things for a bit longer to see
whether STYLE by default is too much.

jmc

Post by Ingo Schwarze
In general, i don't like adding knobs. But when the choice is
between having innocent people harassed with false positives and
between providing a knob for saying which checks you want, in a way
that is actually needed in practice, then i prefer the knob to the
harassment.
OK for the patch below?

Post by Sebastien Marie
According to mandoc man page, -Wwarning will avoid all styles warning.

The list of messages is also in the mandoc(1) manual, with an
explanation of each message.
Yours,
Ingo
Index: main.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/main.c,v
retrieving revision 1.195
diff -u -p -r1.195 main.c
--- main.c 3 Jun 2017 12:16:19 -0000 1.195
+++ main.c 21 Jun 2017 15:09:46 -0000
@@ -68,8 +68,8 @@ enum outt {
struct curparse {
struct mparse *mp;
- enum mandoclevel wlevel; /* ignore messages below this */
int wstop; /* stop after a file with a warning */
+ enum mandocerr mmin; /* ignore messages below this */
enum outt outtype; /* which output to use */
void *outdata; /* data for output */
struct manoutput *outopts; /* output options */
@@ -159,7 +159,7 @@ main(int argc, char *argv[])
memset(&curp, 0, sizeof(struct curparse));
curp.outtype = OUTT_LOCALE;
- curp.wlevel = MANDOCLEVEL_BADARG;
+ curp.mmin = MANDOCERR_MAX;
curp.outopts = &conf.output;
options = MPARSE_SO | MPARSE_UTF8 | MPARSE_LATIN1;
defos = NULL;
@@ -416,7 +416,7 @@ main(int argc, char *argv[])
moptions(&options, auxpaths);
mchars_alloc();
- curp.mp = mparse_alloc(options, curp.wlevel, mmsg, defos);
+ curp.mp = mparse_alloc(options, curp.mmin, mmsg, defos);
/*
* Conditionally start up the lookaside buffer before parsing.
@@ -907,7 +907,7 @@ toptions(struct curparse *curp, char *ar
curp->outtype = OUTT_ASCII;
else if (0 == strcmp(arg, "lint")) {
curp->outtype = OUTT_LINT;
- curp->wlevel = MANDOCLEVEL_STYLE;
+ curp->mmin = MANDOCERR_STYLE;
} else if (0 == strcmp(arg, "tree"))
curp->outtype = OUTT_TREE;
else if (0 == strcmp(arg, "man"))
@@ -936,16 +936,17 @@ static int
woptions(struct curparse *curp, char *arg)
{
char *v, *o;
- const char *toks[8];
+ const char *toks[9];
toks[0] = "stop";
toks[1] = "all";
toks[2] = "style";
- toks[3] = "warning";
- toks[4] = "error";
- toks[5] = "unsupp";
- toks[6] = "fatal";
- toks[7] = NULL;
+ toks[3] = "portable";
+ toks[4] = "warning";
+ toks[5] = "error";
+ toks[6] = "unsupp";
+ toks[7] = "fatal";
+ toks[8] = NULL;
while (*arg) {
o = arg;
@@ -955,19 +956,22 @@ woptions(struct curparse *curp, char *ar
break;
- curp->wlevel = MANDOCLEVEL_STYLE;
+ curp->mmin = MANDOCERR_STYLE;
break;
- curp->wlevel = MANDOCLEVEL_WARNING;
+ curp->mmin = MANDOCERR_PORTABLE;
break;
- curp->wlevel = MANDOCLEVEL_ERROR;
+ curp->mmin = MANDOCERR_WARNING;
break;
- curp->wlevel = MANDOCLEVEL_UNSUPP;
+ curp->mmin = MANDOCERR_ERROR;
break;
- curp->wlevel = MANDOCLEVEL_BADARG;
+ curp->mmin = MANDOCERR_UNSUPP;
+ break;
+ curp->mmin = MANDOCERR_MAX;
break;
warnx("-W %s: Bad argument", o);
Index: mandoc.1
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.1,v
retrieving revision 1.125
diff -u -p -r1.125 mandoc.1
--- mandoc.1 17 Jun 2017 23:06:43 -0000 1.125
+++ mandoc.1 21 Jun 2017 15:09:46 -0000
@@ -158,7 +158,12 @@ or
.Cm unsupp ;
.Cm all
is an alias for
-.Cm style .
+.Cm style ,
+and
+.Cm portable
+is a variant of
+.Cm style
+hiding style recommendations that only apply to base system manuals.
By default,
.Nm
is silent.
@@ -746,7 +751,7 @@ are hidden unless their level, or a lowe
option or
.Fl T Cm lint
output mode.
-.Ss Style messages
+.Pp
As indicated below, some style checks are only performed if a
specific operating system name occurs in the arguments of the
.Ic \&Os
@@ -756,6 +761,10 @@ command line option, or, if neither are
of the
.Xr uname 3
function.
+.Ss Style messages for base system manuals
+These are not shown if
+.Fl W Cm portable
+is specified.
.Bl -ohang
.It Sy "Mdocdate found"
.Pq mdoc , Nx
@@ -778,6 +787,17 @@ macro does not use CVS
keyword substitution, but using it is conventionally expected in the
.Ox
base system.
+.It Sy "RCS id missing"
+.Pq Ox , Nx
+The manual page lacks the comment line with the RCS identifier
+generated by CVS
+.Ic OpenBSD
+or
+.Ic NetBSD
+keyword substitution as conventionally used in these operating systems.
+.El
+.Ss Style messages for all manual pages
+.Bl -ohang
.It Sy "legacy man(7) date format"
.Pq mdoc
The
@@ -791,14 +811,6 @@ Consider using the conventional
date format
.Dq "Month dd, yyyy"
instead.
-.It Sy "RCS id missing"
-.Pq Ox , Nx
-The manual page lacks the comment line with the RCS identifier
-generated by CVS
-.Ic OpenBSD
-or
-.Ic NetBSD
-keyword substitution as conventionally used in these operating systems.
.It Sy "duplicate RCS id"
A single manual page contains two copies of the RCS identifier for
the same operating system.
Index: mandoc.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.h,v
retrieving revision 1.174
diff -u -p -r1.174 mandoc.h
--- mandoc.h 17 Jun 2017 23:06:43 -0000 1.174
+++ mandoc.h 21 Jun 2017 15:09:46 -0000
@@ -48,8 +48,11 @@ enum mandocerr {
MANDOCERR_MDOCDATE, /* Mdocdate found: Dd ... */
MANDOCERR_MDOCDATE_MISSING, /* Mdocdate missing: Dd ... */
- MANDOCERR_DATE_LEGACY, /* legacy man(7) date format: Dd ... */
MANDOCERR_RCS_MISSING, /* RCS id missing */
+
+ MANDOCERR_PORTABLE, /* ===== style hints for portable ===== */
+
+ MANDOCERR_DATE_LEGACY, /* legacy man(7) date format: Dd ... */
MANDOCERR_RCS_REP, /* duplicate RCS id: ... */
MANDOCERR_MACRO_USELESS, /* useless macro: macro */
MANDOCERR_BX, /* consider using OS macro: macro */
@@ -448,7 +451,7 @@ const char *mchars_uc2str(int);
int mchars_num2uc(const char *, size_t);
int mchars_spec2cp(const char *, size_t);
const char *mchars_spec2str(const char *, size_t, size_t *);
-struct mparse *mparse_alloc(int, enum mandoclevel, mandocmsg, const char *);
+struct mparse *mparse_alloc(int, enum mandocerr, mandocmsg, const char *);
void mparse_free(struct mparse *);
void mparse_keep(struct mparse *);
int mparse_open(struct mparse *, const char *);
Index: read.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/read.c,v
retrieving revision 1.150
diff -u -p -r1.150 read.c
--- read.c 17 Jun 2017 23:06:43 -0000 1.150
+++ read.c 21 Jun 2017 15:09:46 -0000
@@ -52,7 +52,7 @@ struct mparse {
const char *defos; /* default operating system */
mandocmsg mmsg; /* warning/error message handler */
enum mandoclevel file_status; /* status of current parse */
- enum mandoclevel wlevel; /* ignore messages below this */
+ enum mandocerr mmin; /* ignore messages below this */
int options; /* parser options */
int gzip; /* current input file is gzipped */
int filenc; /* encoding of the current file */
@@ -82,12 +82,15 @@ static const enum mandocerr mandoclimits
static const char * const mandocerrs[MANDOCERR_MAX] = {
"ok",
- "generic style suggestion",
+ "base system convention",
"Mdocdate found",
"Mdocdate missing",
- "legacy man(7) date format",
"RCS id missing",
+
+ "generic style suggestion",
+
+ "legacy man(7) date format",
"duplicate RCS id",
"useless macro",
"consider using OS macro",
@@ -738,7 +741,7 @@ mparse_open(struct mparse *curp, const c
}
struct mparse *
-mparse_alloc(int options, enum mandoclevel wlevel, mandocmsg mmsg,
+mparse_alloc(int options, enum mandocerr mmin, mandocmsg mmsg,
const char *defos)
{
struct mparse *curp;
@@ -746,7 +749,7 @@ mparse_alloc(int options, enum mandoclev
curp = mandoc_calloc(1, sizeof(struct mparse));
curp->options = options;
- curp->wlevel = wlevel;
+ curp->mmin = mmin;
curp->mmsg = mmsg;
curp->defos = defos;
@@ -838,12 +841,12 @@ mandoc_msg(enum mandocerr er, struct mpa
{
enum mandoclevel level;
+ if (er < m->mmin && er != MANDOCERR_FILE)
+ return;
+
level = MANDOCLEVEL_UNSUPP;
while (er < mandoclimits[level])
level--;
-
- if (level < m->wlevel && er != MANDOCERR_FILE)
- return;
if (m->mmsg)
(*m->mmsg)(er, level, m->file, ln, col, msg);

Ingo Schwarze

2017-06-21 23:18:05 UTC

Hi Jason,

Post by Ingo Schwarze
As there is no fully satisfactory option, i propose the patch below.
It add the "-W portable" command line option, which is a variant of
"-W style" hiding messages that only apply to base system manuals.

i'm not entirely convinced... are there likely to be other style
warnings that apply to our base manuals but not "portable"?
if there's a list of things then maybe it makes sense.

Quite likely in the future:

- In base, we only want sections 1-9 and 3p.
In third-party software, sections like "n" (for TCL)
or "3f" (for Fortran) may be legitimate.

- In base, we have a fixed list of architectures that we want
to check the third .Dt argument against.
In portable software, architectures that do not exist in OpenBSD
may be legitimate.

- In base, we probably want to warn about standard .Sh sections
that we don't use in OpenBSD (like LIBRARY).
In portable software, a LIBRARY section may be legitimate, if
the software is also targetting systems like FreeBSD, NetBSD,
or Linux where that section is in widespread use (and actually
somewhat useful because they either have such a vast swamp of
libraries in base, or no clear distinction between base and
ports at all).

- In base, we always want to warn in case the .Os macro has any
argument whatsoever.
In portable software, an .Os argument may be deliberate.

Post by Jason McIntyre
otherwise i wonder if we can;t try and make things clearer (style
warning is not a mistake) and leave things for a bit longer to see
whether STYLE by default is too much.

I think we may have a better chance to show that STYLE by default
is not too much if we prevent the above false positives from slowly
piling up in the first place.

Also, i don't quite understand what you mean that could be made
clearer, the mandoc(1) manual is already quite explicit:

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 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 style suggestion
really justifies a change to the input file.

Yours,
Ingo

Jason McIntyre

2017-06-22 06:31:49 UTC

Post by Ingo Schwarze
Hi Jason,

i'm not entirely convinced... are there likely to be other style
warnings that apply to our base manuals but not "portable"?
if there's a list of things then maybe it makes sense.

- In base, we only want sections 1-9 and 3p.
In third-party software, sections like "n" (for TCL)
or "3f" (for Fortran) may be legitimate.
- In base, we have a fixed list of architectures that we want
to check the third .Dt argument against.
In portable software, architectures that do not exist in OpenBSD
may be legitimate.
- In base, we probably want to warn about standard .Sh sections
that we don't use in OpenBSD (like LIBRARY).
In portable software, a LIBRARY section may be legitimate, if
the software is also targetting systems like FreeBSD, NetBSD,
or Linux where that section is in widespread use (and actually
somewhat useful because they either have such a vast swamp of
libraries in base, or no clear distinction between base and
ports at all).
- In base, we always want to warn in case the .Os macro has any
argument whatsoever.
In portable software, an .Os argument may be deliberate.

fair enough then, if you think it's worth doing. but aren't you worried that
you're gonna end up with all operating systems/interested parties wanting
their own flags?

jmc

Ingo Schwarze

2017-06-23 17:24:31 UTC

Hi Jason,

Post by Jason McIntyre
i'm not entirely convinced... are there likely to be other style
warnings that apply to our base manuals but not "portable"?
if there's a list of things then maybe it makes sense.

[ ... 4 examples deleted ... ]

fair enough then, if you think it's worth doing.
but aren't you worried that you're gonna end up with all
operating systems/interested parties wanting their own flags?

Not worried, no. I'm not expecting that many, a handful at most,
and even a dozen would be less of a maintenance burden than many
of the switch/case features contained in the mdoc(7) language itself.

- illumos, definitely.
- FreeBSD, maybe. I have no indication yet that they may want
to use the feature, but it would fit their culture.
- Debian, possibly. If there is something that they can tweak,
they usually tweak it. If there is not, they tweak it anyway.
But i guess it will take several years before they find out.
They don't move all that fast, you know.

- Alpine, Void, Arch, Slackware, Crux Linux:
Very unlikely. They tend to refrain from customization, and
from creatung unnecessary maintenance workload for themselves,
whenever they can.

- DragonFly, Minix, MacOS X:
Very unlikely. These projects look like abandonware to me.

No other project is actively using mandoc at this point.
It also runs on IBM AIX and Oracle Solaris, and there are many
unofficial, outdated ports for major Linux distros, but none of
these will request their own -Tlint customizations.

Yours,
Ingo

Jason McIntyre

2017-06-23 19:30:44 UTC

Post by Ingo Schwarze
Hi Jason,

[ ... 4 examples deleted ... ]

fair enough then, if you think it's worth doing.
but aren't you worried that you're gonna end up with all
operating systems/interested parties wanting their own flags?

Not worried, no. I'm not expecting that many, a handful at most,
and even a dozen would be less of a maintenance burden than many
of the switch/case features contained in the mdoc(7) language itself.
- illumos, definitely.
- FreeBSD, maybe. I have no indication yet that they may want
to use the feature, but it would fit their culture.
- Debian, possibly. If there is something that they can tweak,
they usually tweak it. If there is not, they tweak it anyway.
But i guess it will take several years before they find out.
They don't move all that fast, you know.
Very unlikely. They tend to refrain from customization, and
from creatung unnecessary maintenance workload for themselves,
whenever they can.
Very unlikely. These projects look like abandonware to me.
No other project is actively using mandoc at this point.
It also runs on IBM AIX and Oracle Solaris, and there are many
unofficial, outdated ports for major Linux distros, but none of
these will request their own -Tlint customizations.
Yours,
Ingo

evening.

thanks for answering my questions. so i have no objections.

jmc

Jeremie Courreges-Anglas

2017-06-21 23:24:00 UTC

Post by Ingo Schwarze
Hi Sebastien and Jeremie,

Post by Sebastien Marie

Post by Sebastien Marie
But mandoc -Tlint complains about missing Mdocdate.
$ mandoc -Tlint sysclean.8
mandoc: sysclean.8:17:5: STYLE: Mdocdate missing: Dd June

With another project, I get this warning about Dd, plus a message
about a missing RCS Id.

ah, I don't have this one. But after checking, my man page has a
$OpenBSD$ tag inside it... it should come from the mdoc.template I
used to start writing the file. :)
If I remove it, I have the same STYLE warning.

Even if I was fine with option 1, I was going to ok Ingo's diff, since
it helps people who use mandoc but don't care about RCS keywords.

However I think Jason may have a point.

Post by Jason McIntyre
evening.
i'm not entirely convinced... are there likely to be other style
warnings that apply to our base manuals but not "portable"? if there's a
list of things then maybe it makes sense.
otherwise i wonder if we can;t try and make things clearer (style
warning is not a mistake)

Well, if a style warning is not a mistake, then should the exit status
be 1?

~/src/ratpoison/doc$ mandoc -Tlint ratpoison.mdoc.1 ; echo $?
mandoc: ratpoison.mdoc.1:25:5: STYLE: Mdocdate missing: Dd May
mandoc: ratpoison.mdoc.1: STYLE: RCS id missing
1

Post by Jason McIntyre
and leave things for a bit longer to see
whether STYLE by default is too much.

But are those actually style warnings, or errors? "STYLE" alone is a bit of
a misnomer, the warnings above talk about cvs because OpenBSD and NetBSD
use certain RCS keywords. Maybe this kind of error should only trigger
when checking OpenBSD/NetBSD manpages, and the error message should
mention "OS" or OPENBSD" (or whatever is needed for people to decide
whether they care). Wouldn't this kind of check be more suitable for
the "manlint" target in bsd.man.mk?

Also, what would be the default behavior for portable mandoc?

Sorry for bringing more questions than answers. :)

Post by Jason McIntyre
jmc

Post by Sebastien Marie
According to mandoc man page, -Wwarning will avoid all styles warning.

The list of messages is also in the mandoc(1) manual, with an
explanation of each message.
Yours,
Ingo
Index: main.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/main.c,v
retrieving revision 1.195
diff -u -p -r1.195 main.c
--- main.c 3 Jun 2017 12:16:19 -0000 1.195
+++ main.c 21 Jun 2017 15:09:46 -0000
@@ -68,8 +68,8 @@ enum outt {
struct curparse {
struct mparse *mp;
- enum mandoclevel wlevel; /* ignore messages below this */
int wstop; /* stop after a file with a warning */
+ enum mandocerr mmin; /* ignore messages below this */
enum outt outtype; /* which output to use */
void *outdata; /* data for output */
struct manoutput *outopts; /* output options */
@@ -159,7 +159,7 @@ main(int argc, char *argv[])
memset(&curp, 0, sizeof(struct curparse));
curp.outtype = OUTT_LOCALE;
- curp.wlevel = MANDOCLEVEL_BADARG;
+ curp.mmin = MANDOCERR_MAX;
curp.outopts = &conf.output;
options = MPARSE_SO | MPARSE_UTF8 | MPARSE_LATIN1;
defos = NULL;
@@ -416,7 +416,7 @@ main(int argc, char *argv[])
moptions(&options, auxpaths);
mchars_alloc();
- curp.mp = mparse_alloc(options, curp.wlevel, mmsg, defos);
+ curp.mp = mparse_alloc(options, curp.mmin, mmsg, defos);
/*
* Conditionally start up the lookaside buffer before parsing.
@@ -907,7 +907,7 @@ toptions(struct curparse *curp, char *ar
curp->outtype = OUTT_ASCII;
else if (0 == strcmp(arg, "lint")) {
curp->outtype = OUTT_LINT;
- curp->wlevel = MANDOCLEVEL_STYLE;
+ curp->mmin = MANDOCERR_STYLE;
} else if (0 == strcmp(arg, "tree"))
curp->outtype = OUTT_TREE;
else if (0 == strcmp(arg, "man"))
@@ -936,16 +936,17 @@ static int
woptions(struct curparse *curp, char *arg)
{
char *v, *o;
- const char *toks[8];
+ const char *toks[9];
toks[0] = "stop";
toks[1] = "all";
toks[2] = "style";
- toks[3] = "warning";
- toks[4] = "error";
- toks[5] = "unsupp";
- toks[6] = "fatal";
- toks[7] = NULL;
+ toks[3] = "portable";
+ toks[4] = "warning";
+ toks[5] = "error";
+ toks[6] = "unsupp";
+ toks[7] = "fatal";
+ toks[8] = NULL;
while (*arg) {
o = arg;
@@ -955,19 +956,22 @@ woptions(struct curparse *curp, char *ar
break;
- curp->wlevel = MANDOCLEVEL_STYLE;
+ curp->mmin = MANDOCERR_STYLE;
break;
- curp->wlevel = MANDOCLEVEL_WARNING;
+ curp->mmin = MANDOCERR_PORTABLE;
break;
- curp->wlevel = MANDOCLEVEL_ERROR;
+ curp->mmin = MANDOCERR_WARNING;
break;
- curp->wlevel = MANDOCLEVEL_UNSUPP;
+ curp->mmin = MANDOCERR_ERROR;
break;
- curp->wlevel = MANDOCLEVEL_BADARG;
+ curp->mmin = MANDOCERR_UNSUPP;
+ break;
+ curp->mmin = MANDOCERR_MAX;
break;
warnx("-W %s: Bad argument", o);
Index: mandoc.1
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.1,v
retrieving revision 1.125
diff -u -p -r1.125 mandoc.1
--- mandoc.1 17 Jun 2017 23:06:43 -0000 1.125
+++ mandoc.1 21 Jun 2017 15:09:46 -0000
@@ -158,7 +158,12 @@ or
.Cm unsupp ;
.Cm all
is an alias for
-.Cm style .
+.Cm style ,
+and
+.Cm portable
+is a variant of
+.Cm style
+hiding style recommendations that only apply to base system manuals.
By default,
.Nm
is silent.
@@ -746,7 +751,7 @@ are hidden unless their level, or a lowe
option or
.Fl T Cm lint
output mode.
-.Ss Style messages
+.Pp
As indicated below, some style checks are only performed if a
specific operating system name occurs in the arguments of the
.Ic \&Os
@@ -756,6 +761,10 @@ command line option, or, if neither are
of the
.Xr uname 3
function.
+.Ss Style messages for base system manuals
+These are not shown if
+.Fl W Cm portable
+is specified.
.Bl -ohang
.It Sy "Mdocdate found"
.Pq mdoc , Nx
@@ -778,6 +787,17 @@ macro does not use CVS
keyword substitution, but using it is conventionally expected in the
.Ox
base system.
+.It Sy "RCS id missing"
+.Pq Ox , Nx
+The manual page lacks the comment line with the RCS identifier
+generated by CVS
+.Ic OpenBSD
+or
+.Ic NetBSD
+keyword substitution as conventionally used in these operating systems.
+.El
+.Ss Style messages for all manual pages
+.Bl -ohang
.It Sy "legacy man(7) date format"
.Pq mdoc
The
@@ -791,14 +811,6 @@ Consider using the conventional
date format
.Dq "Month dd, yyyy"
instead.
-.It Sy "RCS id missing"
-.Pq Ox , Nx
-The manual page lacks the comment line with the RCS identifier
-generated by CVS
-.Ic OpenBSD
-or
-.Ic NetBSD
-keyword substitution as conventionally used in these operating systems.
.It Sy "duplicate RCS id"
A single manual page contains two copies of the RCS identifier for
the same operating system.
Index: mandoc.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.h,v
retrieving revision 1.174
diff -u -p -r1.174 mandoc.h
--- mandoc.h 17 Jun 2017 23:06:43 -0000 1.174
+++ mandoc.h 21 Jun 2017 15:09:46 -0000
@@ -48,8 +48,11 @@ enum mandocerr {
MANDOCERR_MDOCDATE, /* Mdocdate found: Dd ... */
MANDOCERR_MDOCDATE_MISSING, /* Mdocdate missing: Dd ... */
- MANDOCERR_DATE_LEGACY, /* legacy man(7) date format: Dd ... */
MANDOCERR_RCS_MISSING, /* RCS id missing */
+
+ MANDOCERR_PORTABLE, /* ===== style hints for portable ===== */
+
+ MANDOCERR_DATE_LEGACY, /* legacy man(7) date format: Dd ... */
MANDOCERR_RCS_REP, /* duplicate RCS id: ... */
MANDOCERR_MACRO_USELESS, /* useless macro: macro */
MANDOCERR_BX, /* consider using OS macro: macro */
@@ -448,7 +451,7 @@ const char *mchars_uc2str(int);
int mchars_num2uc(const char *, size_t);
int mchars_spec2cp(const char *, size_t);
const char *mchars_spec2str(const char *, size_t, size_t *);
-struct mparse *mparse_alloc(int, enum mandoclevel, mandocmsg, const char *);
+struct mparse *mparse_alloc(int, enum mandocerr, mandocmsg, const char *);
void mparse_free(struct mparse *);
void mparse_keep(struct mparse *);
int mparse_open(struct mparse *, const char *);
Index: read.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/read.c,v
retrieving revision 1.150
diff -u -p -r1.150 read.c
--- read.c 17 Jun 2017 23:06:43 -0000 1.150
+++ read.c 21 Jun 2017 15:09:46 -0000
@@ -52,7 +52,7 @@ struct mparse {
const char *defos; /* default operating system */
mandocmsg mmsg; /* warning/error message handler */
enum mandoclevel file_status; /* status of current parse */
- enum mandoclevel wlevel; /* ignore messages below this */
+ enum mandocerr mmin; /* ignore messages below this */
int options; /* parser options */
int gzip; /* current input file is gzipped */
int filenc; /* encoding of the current file */
@@ -82,12 +82,15 @@ static const enum mandocerr mandoclimits
static const char * const mandocerrs[MANDOCERR_MAX] = {
"ok",
- "generic style suggestion",
+ "base system convention",
"Mdocdate found",
"Mdocdate missing",
- "legacy man(7) date format",
"RCS id missing",
+
+ "generic style suggestion",
+
+ "legacy man(7) date format",
"duplicate RCS id",
"useless macro",
"consider using OS macro",
@@ -738,7 +741,7 @@ mparse_open(struct mparse *curp, const c
}
struct mparse *
-mparse_alloc(int options, enum mandoclevel wlevel, mandocmsg mmsg,
+mparse_alloc(int options, enum mandocerr mmin, mandocmsg mmsg,
const char *defos)
{
struct mparse *curp;
@@ -746,7 +749,7 @@ mparse_alloc(int options, enum mandoclev
curp = mandoc_calloc(1, sizeof(struct mparse));
curp->options = options;
- curp->wlevel = wlevel;
+ curp->mmin = mmin;
curp->mmsg = mmsg;
curp->defos = defos;
@@ -838,12 +841,12 @@ mandoc_msg(enum mandocerr er, struct mpa
{
enum mandoclevel level;
+ if (er < m->mmin && er != MANDOCERR_FILE)
+ return;
+
level = MANDOCLEVEL_UNSUPP;
while (er < mandoclimits[level])
level--;
-
- if (level < m->wlevel && er != MANDOCERR_FILE)
- return;
if (m->mmsg)
(*m->mmsg)(er, level, m->file, ln, col, msg);

--
jca | PGP : 0x1524E7EE / 5135 92C1 AD36 5293 2BDF DDCC 0DFA 74AE 1524 E7EE

Ingo Schwarze

2017-06-22 00:16:29 UTC

Hi Jeremie,

Post by Jeremie Courreges-Anglas
Well, if a style warning is not a mistake, then should the exit status
be 1?
~/src/ratpoison/doc$ mandoc -Tlint ratpoison.mdoc.1 ; echo $?
mandoc: ratpoison.mdoc.1:25:5: STYLE: Mdocdate missing: Dd May
mandoc: ratpoison.mdoc.1: STYLE: RCS id missing
1

I think so, yes. For mandoc, non-zero exit status means: "You
told me that you care about messages of LEVEL or more, and there
was at least one of these." You said -Tlint, and that implies
-Wall. The numeric value encodes the severity of the message, and
STYLE (1) is the lowest severity.

When you don't care about STYLE messages, you can use -Wwarning,
and then it will exit 0 as you maybe expected.

Post by Jeremie Courreges-Anglas
But are those actually style warnings, or errors? "STYLE" alone is a
bit of a misnomer, the warnings above talk about cvs because OpenBSD
and NetBSD use certain RCS keywords. Maybe this kind of error should
only trigger when checking OpenBSD/NetBSD manpages,

It does as far as that can be detected. These checks are only done
when "OpenBSD" appears in .Os or -Ios= or uname(3).

That detection cannot be perfect because OpenBSD base manuals do
not contain any data explicitly saying that they are OpenBSD pages.
So if we want them to be run on our base system pages by default,
we must use uname(3) and ask people who want to check non-OpenBSD
pages on OpenBSD to use -Wportable or -Ios= or .Os to make their
intent clear.

Post by Jeremie Courreges-Anglas
and the error message should mention "OS" or OPENBSD" (or whatever
is needed for people to decide whether they care).

I could easily include "OpenBSD" or "NetBSD" into these messages,
but i don't see the usefulness and would rather keep them concise.
I'm sure people almost always know for which system they are
checking and don't need to be told. If they really get confused,
they can easily check .Os, -Ios=, and uname(1) to understand
what is going on. Also, the DIAGNOSTICS section in the mandoc(1)
manual already explains which messages are OS-specific and which
systems they apply to.

Post by Jeremie Courreges-Anglas
Wouldn't this kind of check be more suitable for
the "manlint" target in bsd.man.mk?

I don't think so. For one thing, we are trying to reduce the number
of tools needed to properly check manual pages. In the past,
there have been mandoc -Tlint, mdoclint, and the manlint target.
I am working towards full integration of all mdoclint functionality
into mandoc, such that jmc@ (and others) get all the information
from one call and don't have to waste time running multiple tools.
Besides, the manlint target in bsd.man.mk is practically obsolete
nowadays, i haven't used it in years. It was quite handy when we
installed *formatted* manuals many years ago. Today, you can simply
run mandoc -Tlint in /usr/share/man/.
And even if we want to keep the manlint target, all it does is call
mandoc -Tlint. Trying to implement additional checks that are not
in mandoc -Tlint, in particular intelligent semantic ones that
require parsing the manual, directly in the Makefile without running
the mandoc parser, seems like a very bad idea to me, if it is
feasible at all.

Post by Jeremie Courreges-Anglas
Also, what would be the default behavior for portable mandoc?

No difference from base-system OpenBSD or NetBSD mandoc:
Get the operating system from .Os, -Ios=, or uname(3).
If it is OpenBSD, then run the OpenBSD style checks;
if it is NetBSD, run the NetBSD style checks;
if it is anything else, run no OS-specific style checks,
but only the OS-independent style checks.

Post by Jeremie Courreges-Anglas
Sorry for bringing more questions than answers. :)

No problem, they can all be answered!

Yours,
Ingo

Ted Unangst

2017-06-22 00:48:48 UTC

I'm not fond of the name portable. To me, this suggests it will check for
things which impede portability, but that's not really what it does. It may
have that effect in some cases, but more as an incidental effect.

Instead, I suggest shifting the names by one. Leave -W style as the portable
option, but introduce -W openbsd which performs the additional checks. Or
better, name it -W system, so as to be useful on netbsd, etc.

I think this matches the actual hierarchy in practice. There's errors and
warnings at the top. Then there's general style warnings. Then below that
there's the local system specific style guidelines. It's a matter of
perspective, but the portable warnings aren't subset of style, rather the
system warnings are a superset of style.

Jeremie Courreges-Anglas

2017-06-22 01:05:41 UTC

Post by Ted Unangst

That sounds reasonable too...

Post by Ted Unangst
I think this matches the actual hierarchy in practice. There's errors and
warnings at the top. Then there's general style warnings. Then below that
there's the local system specific style guidelines. It's a matter of
perspective, but the portable warnings aren't subset of style, rather the
system warnings are a superset of style.

--
jca | PGP : 0x1524E7EE / 5135 92C1 AD36 5293 2BDF DDCC 0DFA 74AE 1524 E7EE

Ingo Schwarze

2017-06-22 01:13:36 UTC

Hi Ted,

I'm not fond of the name portable. To me, this suggests it will check
for things which impede portability, but that's not really what it does.

True. That might indeed cause misunderstandings.

Instead, I suggest shifting the names by one. Leave -W style as the
portable option, but introduce -W openbsd which performs the additional
checks. Or better, name it -W system, so as to be useful on netbsd, etc.

That's a fine idea! I'll send a revised patch tomorrow.

Actually, i prefer calling the option -W openbsd.

In cases where you have to specify the option, -W openbsd is not
harder to type than -W system, and clearer. It also saves you
the additional work of having to type -Ios=OpenBSD in cases where
that would be needed. And it has the additional benefit of allowing
to explicitly request OpenBSD-specific checks even on manuals that
contain bogus .Os arguments.

In cases where you don't specify -W but only -Tlint, the system
can be picked from .Os, -Ios=, or uname(3) just like it is now.

And developers maintaining portable software can simply use
mandoc -Tlint -Wstyle to check their own manuals. That's a nice
and clear name.

I think this matches the actual hierarchy in practice. There's errors
and warnings at the top. Then there's general style warnings.
Then below that there's the local system specific style guidelines.
It's a matter of perspective, but the portable warnings aren't subset
of style, rather the system warnings are a superset of style.

Makes sense.

Thanks,
Ingo

Ingo Schwarze

2017-06-22 15:16:23 UTC