discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
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

  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).