* Re: Re: [Groff] How to find bugs in man pages?
[not found] ` <fb67685c-a503-f27e-3f3a-ef3839fa5a0e-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
@ 2016-08-08 19:43 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 2+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-08-08 19:43 UTC (permalink / raw)
To: Xose Vazquez Perez; +Cc: linux-man
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
^ permalink raw reply [flat|nested] 2+ messages in thread