Re: Warn on semantic newlines

[Alejandro Colomar]

[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