Lint generated manual pages
For man page generation we rely on Sphinx and DocBook (v9_11
) and although we don't control the manual page output, we may lint them with mandoc -T lint
and thus try harder in CI to produce legible content.
On main
and v9_16
only three types of warnings and no errors are produced:
$ find doc/man/ -not -path '*/_build/*' -name "*.[0-9]" -exec mandoc -Tlint "{}" \;
WARNING: skipping paragraph macro: sp after SH
WARNING: unknown font, skipping request: ft C
WARNING: skipping paragraph macro: sp after SS
There are more types of warnings and one type of error on v9_11
.
We could filter out these and rely on mandoc -T lint
as a sanity check of generated man pages.
The case of #2310 (closed) seems to be covered (though probably only by a chance):
$ find /tmp/mozilla_newman0/bind-9.11.24 -name '*.[0-9]' -not -path '*/tests/*' -not -path '*/contrib/*' -exec mandoc -Tlint -Werror {} \;
$ find /tmp/mozilla_newman0/bind-9.11.25 -name '*.[0-9]' -not -path '*/tests/*' -not -path '*/contrib/*' -exec mandoc -Tlint -Werror {} \;
mandoc: /tmp/mozilla_newman0/bind-9.11.25/bin/named/named.8:189:2: ERROR: skipping unknown macro: .\}
mandoc: /tmp/mozilla_newman0/bind-9.11.25/bin/named/lwresd.8:194:2: ERROR: skipping unknown macro: .\}
The risk here is inherent from the fact that we don't control the generated output and mandoc
may fail CI job, even-thought the content is legible by man(1)
program "standards".
Edited by Michal Nowak