From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mout.gmx.net (mout.gmx.net [212.227.17.21]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id e389cfc5 for ; Sat, 29 Jul 2017 10:18:02 -0500 (EST) Received: from [192.168.1.2] ([188.170.202.126]) by mail.gmx.com (mrgmx102 [212.227.17.174]) with ESMTPSA (Nemesis) id 0Mam2Q-1dIIuR1mEk-00KMgn for ; Sat, 29 Jul 2017 17:12:57 +0200 Subject: Re: mandoc-1.14.2 released To: discuss@mandoc.bsd.lv References: <20170728181244.GD58985@athene.usta.de> <69d1d7f2-ce86-62e1-7623-e1a4c05f6f4d@gmx.com> <20170729142827.GF24945@athene.usta.de> From: Yuri Pankov Message-ID: Date: Sat, 29 Jul 2017 18:12:54 +0300 User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.2.1 X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 In-Reply-To: <20170729142827.GF24945@athene.usta.de> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K0:rGDmBoJ4GimJZzgYojCJsji2uQugmNLbkvWrR6n1JFJJQ1f6xl5 kI4QbXpB6EPt5KlFd/yyMz3aFdezijAXNejLT+k5OyMMROMDlzaH1kdFw9G50p+VTdJ0qu3 ijQY89+K1jgKiPwUkNWu9PLJQUUdPo5xeQvWwxOchb432GzvjfI+rCkklJ5fbOC2pgvl4Bl mZ2N1i4vJdZ4Ads+eJYSA== X-UI-Out-Filterresults: notjunk:1;V01:K0:mmTbJV9xeQI=:KEotrSTZysANbpjA2xoCt5 b37eD847N3CumSDhalZ+PKaKTl9OtdqI+EAXfcEOeDDb55pvY83Wed6FMignMaiawHmZpD+DM SchOf336q3fHhJsSt+TpP46Lgki0mSyJtiTeWj6F7SRY7CBVJSNrwG2eanQkDyfy5HDu9Qtma MI1CuQCgqNpMD0ihbLWuVsWOCeevI2p2ygT5wF1xrnq2ZVVWtbMgy98sz0UXrGMy6H9PMxUkQ fIgXwbHdmv4Pac3WBkUBzqznb8iJ+wq1C4TfbXSM6URFGNxtPI3YU7J7AnZAC4xcL0vI3QiOZ lDsKr8sZg1tCbwUklDEHE3ugYLqGDreF5/EimFHB7kD2i6ZTNCGGM0UZ7ayqJddr0v8pG/ll7 imZno3IuwCS+JI2yJhr94jUbFhabgKx5+hT0VJ5mduiHeheOH71dwaXGj5Jke/mODfiLn72Pv 8zLbn+NOc2udgpckD1w0kVcg68yxupOFArjWG8D+/3KGC0UdDs9Fvh/Xb1GfoPVwxPT2sLb0L 0nuv+DHfwzMhKJ7HlwrjmZJEzBFysH6HynnAaLmuoWwFouatBvbFwZkXjC/XutfZ7pL5dxKhV 3ExSHGSPzqv3y2+K4VvGEvH3uQYmXgxmVglFY2qRwjSnht7k0XGs726Upmzc/w8OURjrMCEZq rFsAcaSEtFI/8U6VWR58PlSe872Htg9QDqIlKkWTCWtxwURG8dsMmp3JLRruwYoQ5Lqmmh6YY Df++OLaPO3p9Xv7Sx4PR57yRLEekqUc2MrJBQVqcZY+nVBsN/BBczIXj4JsD77BQyWW6zDTdX uoyEimtNT/lAM2bN8ap5Hn/OR/4WCJh//62823AjH8mquUeJ33QuhUpA4QLZjga63g/Kfs9 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