discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Yuri Pankov <yuripv@gmx.com>
Cc: discuss@mandoc.bsd.lv
Subject: Re: mandoc-1.14.2 released
Date: Sat, 29 Jul 2017 16:28:27 +0200	[thread overview]
Message-ID: <20170729142827.GF24945@athene.usta.de> (raw)
In-Reply-To: <69d1d7f2-ce86-62e1-7623-e1a4c05f6f4d@gmx.com>

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.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

  reply	other threads:[~2017-07-29 14:28 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 [this message]
2017-07-29 15:12     ` Yuri Pankov
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=20170729142827.GF24945@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=discuss@mandoc.bsd.lv \
    --cc=yuripv@gmx.com \
    /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).