Skip to content

GitLab

BIND
BIND
Closed
Opened by Michal Nowak@mnowakMaintainer

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