Skip to content

GitLab

  • Projects
  • Groups
  • Snippets
  • Help
    • Loading...
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in / Register
BIND
BIND
  • Project overview
    • Project overview
    • Details
    • Activity
    • Releases
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
  • Issues 637
    • Issues 637
    • List
    • Boards
    • Labels
    • Service Desk
    • Milestones
  • Merge Requests 105
    • Merge Requests 105
  • CI / CD
    • CI / CD
    • Pipelines
    • Jobs
    • Schedules
  • Operations
    • Operations
    • Incidents
    • Environments
  • Packages & Registries
    • Packages & Registries
    • Container Registry
  • Analytics
    • Analytics
    • CI / CD
    • Repository
    • Value Stream
  • Wiki
    • Wiki
  • Snippets
    • Snippets
  • Members
    • Members
  • Collapse sidebar
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
  • ISC Open Source Projects
  • BINDBIND
  • Issues
  • #2312

Closed
Open
Opened Nov 26, 2020 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 Dec 07, 2020 by Michal Nowak
Assignee
Assign to
March 2021 (9.11.29, 9.11.29-S1, 9.16.13, 9.16.13-S1, 9.17.11)
Milestone
March 2021 (9.11.29, 9.11.29-S1, 9.16.13, 9.16.13-S1, 9.17.11)
Assign milestone
Time tracking
None
Due date
None
Reference: isc-projects/bind9#2312