From: Yuri Pankov <yuripv@gmx.com>
To: discuss@mandoc.bsd.lv
Subject: Re: mandoc-1.14.2 released
Date: Sat, 29 Jul 2017 18:12:54 +0300 [thread overview]
Message-ID: <de0c0c4f-3200-3efc-86c0-e9554ee3ced8@gmx.com> (raw)
In-Reply-To: <20170729142827.GF24945@athene.usta.de>
On Sat, 29 Jul 2017 16:28:27 +0200, Ingo Schwarze wrote:
> Hi Yuri,
>
> Yuri Pankov Illumos wrote on Sat, Jul 29, 2017 at 04:35:37PM +0300:
>
>> I'm in the process of updating the mandoc version in our tree,
>
> Great. You are working fast. :-)
>
>> and have noticed that man pages bundled with the release are not
>> entirely '-Tlint -Wstyle' clean as reported by 1.14.2 version that
>> I've just built, a lot of noise about man.options.1 (which we don't
>> use though),
>
> Indeed, that one isn't really intended to be installed. The target
> audience are mandoc developers (and developers of other man(1) systems),
> just like for the *.3 pages, which are not installed by default either,
> in particular the internal ones like man.cgi.3, mandoc_headers.3,
> mandoc_html.3.
>
> The man.options.1 file is not a clean mdoc(7) page but uses some
> low-level roff(7) features that are not needed in normal manual
> pages.
>
>> and the ones below:
>>
>> mandoc: /home/yuri/mandoc-1.14.2/mandoc.1:99:20: STYLE: no blank before
>> trailing delimiter: Oo ...;
>> mandoc: /home/yuri/mandoc-1.14.2/mandoc_char.7:204:11: STYLE: no blank
>> before trailing delimiter: Sq \e&.
>> mandoc: /home/yuri/mandoc-1.14.2/mandoc_html.3:272:6: STYLE: no blank
>> before trailing delimiter: Cm s?
>> mandoc: /home/yuri/mandoc-1.14.2/mdoc.7:3076:8: STYLE: no blank before
>> trailing delimiter: Sq \e&.
>> mandoc: /home/yuri/mandoc-1.14.2/roff.7:1868:7: STYLE: trailing
>> delimiter: Ss \e,
>
> That is known, too. It is not easy to get style messages 100% free
> of false positives. That is even documented, see mandoc(1):
>
> 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.
>
> If you cannot tolerate a small number of false positives in the build,
> consider using -Wwarning instead. It wouldn't really help to change
> the mandoc manuals themselves to not issue these five false positives.
> Probably, there are also a few false positives in the rest of your
> tree.
>
> Warning and error messages should almost always be fixed - or else
> reported to me as bogus when they cause false positives, such that
> i can fix them. But making the criteria for style messages even
> stricter such that they never cause false positives would degrade
> their usefulness by making them miss many real issues.
Got it, thanks for explanation! I'll switch the checks to the -Wwarning
level.
There's another issue though which doesn't look entirely correct, sorry,
I didn't check the lint, only formatted output previously.
We have a man page that looks like this (and should stay like that):
$ cat foo_bar.1
.Dd July 29, 2017
.Dt FOO_BAR 1
.Os
.Sh NAME
.Nm foo_bar
.Nd baz
.Sh SYNOPSIS
.Nm foo
.Fl F Sy bar
.Sh DESCRIPTION
baz
.Sh SEE ALSO
.Xr foo 1
and here's the warning:
$ mandoc -Tlint -Wwarning foo_bar.1
mandoc: foo_bar.1:13:5: WARNING: cross reference to self: Xr foo 1
Shouldn't we look only at the NAME section for this check?
--
To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv
next prev parent reply other threads:[~2017-07-29 15:18 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-07-28 18:12 Ingo Schwarze
2017-07-29 13:35 ` Yuri Pankov
2017-07-29 14:28 ` Ingo Schwarze
2017-07-29 15:12 ` Yuri Pankov [this message]
2017-07-29 17:38 ` Ingo Schwarze
2017-07-29 20:09 ` Yuri Pankov
2017-08-02 13:50 ` Ingo Schwarze
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=de0c0c4f-3200-3efc-86c0-e9554ee3ced8@gmx.com \
--to=yuripv@gmx.com \
--cc=discuss@mandoc.bsd.lv \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).