Hello Xose, On 24 June 2016 at 20:14, Xose Vazquez Perez <xose.vazquez@xxxxxxxxx> wrote: > Hi, > > I asked the same question in the groff ml. Ingo Schwarze, > mandoc current maintainer, send very detailed information: > https://lists.gnu.org/archive/html/groff/2016-06/msg00007.html All of the below though are for pages that use "mandoc" mark-up and BSD tools (e.g., no "man -Tlint" in the man pager provided by the Linux "man-db" package). Generally, man pages on Linux seem to mostly use the "man" macros. (Almost all pages in the man-pages project use the "man" macros. There are just three pages that use "mandoc" macros.) Thanks, Michael > -------- Forwarded Message -------- > Subject: Re: [Groff] How to find bugs in man pages? > Date: Tue, 21 Jun 2016 03:18:51 +0200 > From: Ingo Schwarze <schwarze@xxxxxxx> > To: Xose Vazquez Perez <xose.vazquez@xxxxxxxxx> > CC: groff@xxxxxxx > > Hi Xose, > > Ralph Corderoy wrote on Sun, Jun 19, 2016 at 04:10:15PM +0100: >> Xose wrote: > >>> I'm using: groff -z -b -wall manpage.x >>> Is there anything better? > >> Not as far as I know. > > Inside groff, that is. > >> That doesn't complain about these errors. >> >> $ zcat /usr/share/man/man1/bash.1.gz | grep '\. [[:upper:]]' >> compound commands are also limited to this range. Under certain >> it should be bound. The name may be specified in one of two ways: >> is not used. The >> suppressing the normal shell function lookup. Only builtin >> $ >> >> Perhaps a `linter' exists? > > Several linters exist. > > See here what i'm normally using: > > schwarze@isnote $ uname -a > OpenBSD isnote.usta.de 6.0 GENERIC.MP#1875 i386 > schwarze@isnote $ which bash > which: bash: Command not found. > schwarze@isnote $ doas pkg_add bash > quirks-2.239 signed on 2016-06-20T12:38:05Z > bash-4.3.42p0: ok > schwarze@isnote $ which bash > /usr/local/bin/bash > schwarze@isnote $ man -w bash > /usr/local/man/man1/bash.1 > schwarze@isnote $ man -Tlint bash > tmp.txt 2>&1 > schwarze@isnote $ wc tmp.txt > 488 4372 39316 tmp.txt > > So apparently, that is an unusually crappy manual page: The standard > OpenBSD tool for the job reports 488 lines of warnings. > > schwarze@isnote $ which igor > /usr/local/bin/igor > schwarze@isnote $ igor `man -w bash` > tmp.txt 2>&1 schwarze@isnote $ wc tmp.txt > 489 5610 42314 tmp.txt > > That's the standard FreeBSD tool for the job. It agrees that there > are many problems and reports 489 lines of warnings, many of them > not found by OpenBSD man. Admittedly, a handful are due to a defect > in igor(1) which only supports mdoc(7) and not man(7), but most > complaints of igor are valid. > The standard NetBSD tool for the job is mdoclint(1), which also > supports mdoc(7) only and not man(7): > > schwarze@isnote $ perl /usr/src/regress/usr.bin/mdoclint/mdoclint \ > `man -w bash` > tmp.txt 2>&1 > schwarze@isnote $ wc tmp.txt > 549 6817 57839 tmp.txt > > Again, most complaints of mdoclint(1) are valid. > > I gave a tutorial on the subject at EuroBSDCon 2014 in Sofia, > explaining purposes and methods for quality control of manual > pages and comparing the tools: > > http://www.openbsd.org/papers/eurobsdcon2014-mandoc-paper.pdf > (see section 3 on pages 13 to 17) > http://www.openbsd.org/papers/eurobsdcon2014-mandoc-slides.pdf > (see section QA on pages 24 to 32) > https://youtu.be/csA7-SUtUcw?t=58m28s > (Look at that *together* with the PDF slides: You can't read > the slides in the video, but the slides don't contain the > spoken words, so both together are most useful. The part about > QA lasts from t=58m28s until the end of the video, so it's > about 15 minutes to watch. A few facts are slightly outdated > as mandoc development has progressed a lot since 2014 - for > example, mandoc no longer causes any fatal errors, not even > for completely garbage input - but most content is still > accurate today.) > > All these are linked from here: http://mdocml.bsd.lv/press.html > > You can get the software discussed above here: > > Portable mandoc = OpenBSD man(1): http://mdocml.bsd.lv/ > Igor: http://www.wonkity.com/~wblock/igor/ > Mdoclint: http://cvsweb.netbsd.org/bsdweb.cgi/pkgsrc/textproc/mdoclint/ > > Have fun, > Ingo > > -- > To unsubscribe from this list: send the line "unsubscribe linux-man" in > the body of a message to majordomo@xxxxxxxxxxxxxxx > More majordomo info at http://vger.kernel.org/majordomo-info.html -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
