Hi Jeremie, Jeremie Courreges-Anglas wrote on Thu, Jun 22, 2017 at 01:24:00AM +0200:
> 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. > 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. > 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. > 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. > 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. > Sorry for bringing more questions than answers. :) No problem, they can all be answered! Yours, Ingo
