Hi Jason,
Jason McIntyre wrote on Wed, Jun 21, 2017 at 11:10:55PM +0100:
> On Wed, Jun 21, 2017 at 05:22:12PM +0200, Ingo Schwarze wrote:
>> 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.
> 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
