Hi,
Klemens Nanni wrote on Sun, Apr 04, 2021 at 03:54:43PM +0200:
> On Sun, Apr 04, 2021 at 03:42:03PM +0200, Tim van der Molen wrote:
>> Doesn't mandoc -Tlint -Wstyle do what you want?
> I don't think so. Oddly enough, `-Wstyle' does not do what I would
> expect: it omits STYLE messages instead of printing them.
It does not. It only omits BASE messages, which is the lowest message
level and the only one below STYLE. See `man -O tag=base mandoc`
what the purpose of BASE is.
When i inplemented the BASE level, i first printed these messages
with a BASE tag. But other developers complained that "BASE" is
unclear and confusing and requested that STYLE be printed instead.
For that reason, both levels print STYLE. I don't like that, it
is also confusing, just in a different way. But unless you come
up with a name better than "BASE" that other developers will not
complain about, i don't know how to improve it.
You can still visually distinguish STYLE and BASE messages since the
latter have an (OpenBSD) or (NetBSD) tag at the end:
$ man -clT lint /co/NetBSD/src/usr.bin/true/true.1
man: /co/NetBSD/src/usr.bin/true/true.1:34:4: STYLE: duplicate RCS id:
$NetBSD: true.1,v 1.7 2003/08/07 11:16:48 agc Exp $
man: /co/NetBSD/src/usr.bin/true/true.1:36:5: STYLE: Mdocdate missing:
Dd June 27, 1991 (OpenBSD)
man: /co/NetBSD/src/usr.bin/true/true.1: STYLE: RCS id missing: (OpenBSD)
$ man -cT lint -W netbsd true
man: /usr/share/man/man1/true.1:35:5: STYLE: Mdocdate found:
Dd $Mdocdate: September 29 2010 $ (NetBSD)
man: /usr/share/man/man1/true.1: STYLE: RCS id missing: (NetBSD)
>> -Wstyle also suppresses other warnings that aren't interesting for
>> manuals not part of OpenBSD:
Indeed, that's exactly what it was designed for.
> But it would also suppress legitimate messages, e.g. `.Xr' macros with
> misspelled manuals in the base MANPATH:
Yes, so far, checking of .Xr targets is only done on the BASE level,
not on the STYLE level because i regarded the requirement that .Xr targets
exist as a requirement of the OpenBSD base system. For portable software
outside the OpenBSD base system, in the past, i didn't think checking .Xr
targets would be helpful. It appears you now found a use case for that.
Your patch is not OK as it stands because mandoc would no longer help
developers working on the base system to find .Xr links pointing
outside the base system, and we have a policy that we don't want those.
I guess the right thing to do is to leave "-W all" unchanged (including
looking in the base system only) but change "-W style" to also do the .Xr
target check, but along the user's manpath.
Yours,
Ingo
