Re: Re: [Groff] How to find bugs in man pages?

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

Hello Xose,

On 24 June 2016 at 20:14, Xose Vazquez Perez <xose.vazquez-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 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-mcycREo4Un4@public.gmane.org>
> To: Xose Vazquez Perez <xose.vazquez-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> CC: groff-mXXj517/zsQ@public.gmane.org
>
> 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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> 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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html