Maintaining man pages for koha-common as DocBook RFC

From Koha Wiki
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?

Retrieved from "https://wiki.koha-community.org/w/index.php?title=Maintaining_man_pages_for_koha-common_as_DocBook_RFC&oldid=5968"