Work with Documentation

Docbook

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

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.

Generating documentation

We use DocBook XSL stylesheets to transform the Docbook XML to troff manual pages for installation on Unix like systems, or html pages for publishing on the web. The Netatalk build system provides this facility through the -Dbuild-manual configure option, which uses the xsltproc tool on the back end. If your DocBook XSL stylesheet directory isn't automatically detected, use -Dwith-docbook=[path] to tell the build system where it is.

You can also run xsltproc directly, to experiment with various outputs.

Source a non-namespaced copy of docbook-xsl, f.e. from your OS's package repo (on Debian use the docbook-xsl package without the -ns suffix) or from SourceForge, then point the Netatalk build system to the absolute path of where you installed the docbook-xsl styles.

At the time of writing, the final non-namespaced docbook-xsl release is docbook-xsl-1.79.1 on SourceForge. The packages published on GitHub are namespaced by default. See this upstream bug for more info.

Once all requirements are in place, the manual pages will be generated when building Netatalk.

$ meson setup build -Dwith-manual=true
$ meson compile -C build

The generated pages are then found under the build/doc/manual directory.

Generate manual appendix

Run a Python script to refresh the Compilation html manual appendix. Refer to doc/requirements.txt for a list of required Python libraries. Either install system Python libraries, or create a venv with pip.

$ cd doc
$ python3 generate_compile_docs.py 
Wrote to ./manual/compile.xml
Wrote to ./ja/manual/compile.xml

Commit the generated xml files to git in preparation for a new stable netatalk release.

PDF manual

If you want a local PDF manual for reading on the screen or printing, use something like dblatex to transform the XML sources to a variety of formats, including PDF.

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