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

[Ingo Schwarze]

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:

  address@hidden $ uname -a
  OpenBSD isnote.usta.de 6.0 GENERIC.MP#1875 i386
  address@hidden $ which bash
  which: bash: Command not found.
  address@hidden $ doas pkg_add bash
  quirks-2.239 signed on 2016-06-20T12:38:05Z
  bash-4.3.42p0: ok
  address@hidden $ which bash
  /usr/local/bin/bash
  address@hidden $ man -w bash
  /usr/local/man/man1/bash.1
  address@hidden $ man -Tlint bash > tmp.txt 2>&1
  address@hidden $ 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.

  address@hidden $ which igor
  /usr/local/bin/igor
  address@hidden $ igor `man -w bash` > tmp.txt 2>&1 
  address@hidden $ 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):

  address@hidden $ perl /usr/src/regress/usr.bin/mdoclint/mdoclint \
    `man -w bash` > tmp.txt 2>&1
  address@hidden $ 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