Maintaining man pages for koha-common as DocBook RFC

Editing man(ual) pages directly is cumbersome and error-prone and requires knowledge of a rather obscure syntax. A better option might be to edit them as a DocBook document and transform them to whatever we need, including man pages, HTML etc.

Technicalities

man pages

Sample files for koha-create.xml and koha-remove.xml has been created, with documentation for koha-create and koha-remove. Running this command:

xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl/manpages/docbook.xsl koha-*.xml

generates these files:

Use e.g. this to view the results:

man -l koha-remove.8

HTML

koha-common.html was created with this command, as an example of an alternative format:

xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl/xhtml/docbook.xsl koha-*.xml > koha-common.html

Pros

More familiar syntax
Markup is logical, not presentational
Can be handled in the same way as the manual
All man pages can be maintained in one file
?

Cons

?

Where to put the file

There are several options for handling the koha-common.xml file:

Include it in the main koha repository
- debian/docs/
- Could the man pages be generated during installation of koha-common, so that they do not exist as separate files in the repo?
- This might make it harder to integrate the man pages into e.g. the HTML version of the manual, if we should wish to do that
Create a separate git repository for it
Include it in the en/manual.xml file in the kohadocs repository
- This might make it harder to get the *.8 files into the installation
Include it as a separate file in the kohadocs repository
Any other options?

Not sure what will be the best solution?