Testing man pages

When the commands provided by the koha-common Debian package are changed, the man pages for those commands should be changed too. They are maintained as DocBook-files in the debian/docs/ directory. Here are a couple of things that should be done to test changes to these files.

View as man page

This will create a file called koha-somecommand.8 in the directory you are in when you run the command:

 xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/manpages/docbook.xsl debian/docs/koha-somecommand.xml

To view the file you just created:

 man -l koha-somecommand.8

What you see should be a well formed man page, documenting all available options for the command in question etc.

Remember to remove koha-somecommand.8 when you are done.

If you do this testing in koha-testing-docker, "man" will not be installed, but you can install it with:

 sudo apt-get install man

Run relevant tests

Currently there is one test that checks the syntax of the DocBook files:

 prove -v xt/verify-debian-docbook.t

All tests should pass, of course.

If you get this error:

 Can't exec "xmllint": No such file or directory at xt/verify-debian-docbook.t line 31.

...you probably need to install libxml2-utils, which contains xmllint:

 $ sudo apt-get install libxml2-utils

Hints in commit messages

Patches for man pages can contain instructions similar to this:

To test:
Run these commands and look at the formatted man page:
$ xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl/manpages/docbook.xsl \
  debian/docs/koha-mysql.xml
$ man -l koha-mysql.8

Make sure this test passes:
$ prove -v xt/verify-debian-docbook.t