From: Yuri Pankov <email@example.com> To: firstname.lastname@example.org Subject: Re: mandoc-1.14.2 released Date: Sat, 29 Jul 2017 18:12:54 +0300 [thread overview] Message-ID: <email@example.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 firstname.lastname@example.org
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 \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --subject='Re: mandoc-1.14.2 released' \ /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
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).