Work with Documentation

Docbook

Netatalk documentation is maintained in DocBook XML format, which can be transformed to human-readable formats for perusal.

For one, use DocBook XSL stylesheets to transform to for instance troff manual pages, or html pages for publishing on the web. The Netatalk build system provides this facility through the --with-docbook configure option, which uses the xsltproc tool on the back end. You can also run xsltproc directly, to experiment with various outputs.

Another alternative is dblatex which can be used to transform the XML sources to a variety of formats, for instance PDF.

$ dblatex --pdf ./doc/manual/manual.xml

Updating Documentation

The Netatalk documentation consists of two parts: the *NIX manual pages in troff format and the html manual hosted on the website. Both are generated from docbook XML sources housed under the doc/ directory in the source tree.

When making code changes that warrant an update to the documentation, such as adding, changing or deprecating functionality, please make sure the updates to the XML sources for the documentation are included as part of the changeset in your PR.

If the changeset of your PR warrants a bullet point in the changelog, please include an update to the NEWS file as part of your changeset as well.

Docbook editor

A free WYSIWYG editor with only one minor drawback is XMLEditor from XMLmind.

Drawback: in order to be able to edit any of the nested xml files, you have to "promote" them to valid Docbook files by referencing the Docbook DTD, insert as line 2+3:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

These changes will however prevent XMLeditor from opening the master xml file manual.xml. Before further processing or committing to git can be done, these changes then have to be reverted for any changed file.