[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Warn on semantic newlines

From: Alejandro Colomar
Subject: Re: Warn on semantic newlines
Date: Thu, 27 Apr 2023 16:23:03 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.10.0

[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

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?


>  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


GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]