Koha Test Wiki MW Canasta on Koha Portainer
Test major Koha Wiki changes or bug fixes here without fear of breaking the production wiki.
For the current Koha Wiki, visit https://wiki.koha-community.org .Maintaining man pages for koha-common as DocBook RFC
Jump to navigation
Jump to search
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?