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
