[I just realized groff@ was removed; adding back] Hi Ingo,
On 4/27/23 15:34, Ingo Schwarze wrote: [...] > That's only supported for mdoc(7) so far, not for man(7): [...] > The reason is that the mandoc(1) message system strives for low noise, Ahhh, now I remember we already talked about this a long ago. > and since the markup quality of man(7) manual pages is on average lower > than the markup quality of mdoc(7) pages, I hope to have lowered the gap in these years. ;) > this is an example where the > tradeoff is good for mdoc(7) - no noise caused, and the small amount > of warnings issued by this message was easily fixed in the past by > improving the few pages in question - whereas doing the same for man(7) > pages would result in a deluge of warnings, and fixing all those would > be a huge make-work project even in the OpenBSD tree alone. One could always use grep for disabling certain warnings. For completeness, I'll copy again here the way I do it (this time I'll copy the command, rather than the Makefile rule): ! (mandoc -man -Tlint man2/socket.2 2>&1 \ | grep -v 'STYLE: lower case character in document title:' \ | grep -v 'UNSUPP: ignoring macro in table:' \ | grep -v 'WARNING: cannot parse date, using it verbatim: TH (date)' \ | grep -v 'WARNING: empty block: UR' \ | grep -v 'WARNING: missing date, using "": TH' \ | grep -v 'WARNING: undefined escape, printing literally: \\\\' \ ||:; \ ) \ | grep '.' >&2 > Besides, > most man(7) pages in the OpenBSD tree are third-party pages that we > intentionally do not change in our tree in order to not hinder merges > when we later update the third-party software in our tree. Instead, we > ask people to report issues with man(7) pages upstream, and so far, no > one really cared about such minute issues as "new sentence, new line". As I said earlier this week, disabling existing warnings when you don't care about them is easy; the problem is when it's the other way around. > >> Or do you have plans for it (even if not short-term ones)? > > I may have to re-think my strategy in this respect, and also regarding > the relative sparsity of man(7) warnings in general. > > I mean, when the chief maintainer of the Linux manual pages project > starts to care about this particular warning, the above argument > of "no one cares" clearly no longer applies. Also, if you have any other warnings that are generic enough to be useful in man(7) that are currently disabled, consider also enabling them. I might be interested when I see them, and in the worst case, I'll just add one more grep(1). > > I have to consider which category to put the message into, though. > Putting it into the "warning" or even the "style" category would > still cause the deluge of warnings in the OpenBSD tree: that part > of the argument isn't invalidated by Linux Manual Pages project > policy. For example, pod2man(1) does not respect this rule when > converting perlpod(1) pages to man(7), so the warning would be > all over the place in perl(1) documentation. > > My spontaneous idea is to put the warning into the "linux" > category such that it will show up with > > mandoc -T lint -W linux > > and also with just > > mandoc -T lint > > by default if uname(3) returns "Linux". Sounds reasonable, considering you already have -Wopenbsd and -Wnetbsd. To be honest, I'd like a -Weverything as in Clang, where I can turn off anything I don't like. I guess that will be equivalent to `-Tlint -Wopenbsd -Wnetbsd -Wlinux`. If that's the case, that's enough for me. > Yes, that *will* cause a > deluge of warnings for ordinary Linux users, but when *your* official > policy is to try and eventually fix such stuff, that's not necessarily > a bad thing, isn't it? Agree. > Besides, while OpenBSD users are quite used > to concise output of software of any kind in general, Linux users are > much more used to excessively noisy and verbose output - just compare > error messages, log files, or dmesg(1)es between OpenBSD and Linux... > OpenBSD users tend to get quite upset when exposed to gratuitious > verbosity, but i guess many Linux users may not even notice excessive > verbosity as unusual. :-) > > Probably i should also ask Jason McIntyre for his opinion > regarding how to classify the warning for man(7), because he > will be the chief sufferer if i screw up the warning system. > He is using -T lint many times every day. > > What do you think? Sounds good to me. > Ingo Cheers, Alex -- <http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
OpenPGP_signature
Description: OpenPGP digital signature
