In order to improve consistency and reduce review overhead in DocBook contributions thus helping both contributors and maintainers, I’ve been working on a linter/sniffer project called Docbook CS over the past few weeks.
You can find the project here:
And a sample implementation targeting the doc-en repo here:
In the files changed tab you can see in-line failures that were detected by the sniffer.
At the moment, it includes a few focused checks, but is easily possible to add or alter sniffs as desired.
For example:
- Ensuring that when an element has both xml and xmlns attributes or xmlns variants, xml appears first
- Exception or error class names wrapped in <classname> that should use <exceptionname> instead.
- Cases where <simpara> should be used instead of <para>
It can run against the entire doc project or just a subset, such as a git diff, which makes it suitable for both local development and automated checks. It should also be straightforward to use this for other language repositories such as doc-fr.
I’d be interested to hear your thoughts. If it seems useful, perhaps we can add this to the workflow or find another way.
Happy to iterate based on feedback.
Regards,
Jordi