Re: manlint?

[Ingo Schwarze]

Hi Sergiusz,

Sergiusz Pawlowicz wrote on Fri, Sep 11, 2020 at 03:40:50PM +0700:

> is there anything like "manlint"?
> A tool which verifies the syntax of a man file and eventually
> points to errors?

The best such tool i'm aware of is:

   mandoc -T lint $file

It focusses on validating mdoc(7) input and is quite strict with
that.  But it provides validation of man(7) input, too, though
intentionally not quite as strict because real-world man(7) manual
pages are on average of much lower quality than real-world mdoc(7)
manual pages, so the same strictness would result in significantly
more output on average, and if a linter produces large amounts of
output, most users tend to regard that as noise for practical
purposes.  Admittedly one consequence of the choice to be more
lenient with man(7) input is that high-quality man(7) manuals -
small numbers of which can occasionally be found in the wild, even
though they are not at all common - are not validated very strictly
either.

For the documentation, see

  https://man.openbsd.org/mandoc.1
  https://man.openbsd.org/mandoc.1#T
  https://man.openbsd.org/mandoc.1#DIAGNOSTICS

To get the tool, consult

  https://mandoc.bsd.lv/
  https://mandoc.bsd.lv/ports.html

The topic is discussed in detail in my EuroBSDCon 2014 presentation:

  https://www.openbsd.org/papers/eurobsdcon2014-mandoc-slides.pdf
  (pages 24 to 32)

Most of that is still accurate, but

 * Fatal errors have no longer existed for many years.
 * An "unsupp" category has been introduced to flag constructs
   that are even worse for portability than errors.
 * The NetBSD mdoclint(1) tool no longer exists.
   Some years ago, i worked with Thomas Klausner and integrated
   all of its former functionality into mandoc -T lint.
 * The FreeBSD igor(1) tool is not very actively maintained,
   but occasionally still useful as a supplement to mandoc.
 * gmdiff lives at https://cvsweb.bsd.lv/mandoc/gmdiff
 * The remarks about makewhatis(8) -p are strictly OpenBSD-specific.
   That will not be useful on any other system (expect maybe on
   Alpine and Void Linux, i'm not sure).

Of course, as you see from gmdiff, commands similar to the following
will also do some linting, but in a much less systematic way,
catching usually significantly fewer issues, and without extant
documentation regarding the meaning of messages issued:

  groff -ket -ww -mtty-char -Tascii -P -c -mandoc $file

In general, when using groff for linting, i always have to
look up the options, more are required than i can easily
remember...

Your most thorough choice would be to run both gmdiff and igor, but
interpreting the output is not at all trivial and there is a risk
that it will send you on a wild goose chase and confuse you with
significant numbers of false positives.  For almost all practical
use cases except low-level bug fixing in the toolchains, mandoc -T
lint alone is good enough.  For routine checking, even i usually
skip gmdiff and igor and rely on just mandoc -T lint alone.

Yours,
  Ingo