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.
The localized documentation (manual and man pages) needs to be updated as well. Currently, a single localized language is supported: Japanese. These days, Google Translate does a good job with technical documentation. You can drop snippets of XML with embedded text into the translation service and get valid XML back. Just make sure to format the XML afterwards as per the next section.
Docbook editor
A free WYSIWYG editor with only one minor drawback is XMLmind XML Editor.
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 XML tools from opening or parsing 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.
After making manual edits to XML documentation, it is recommended to follow these steps to open and make trivial edits to the XML files through the XMLmind editor. This way, the editor will auto-format the XML code and make it ready to be committed to git.
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.
Once the Python environment is prepared, execute the following script:
$ 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
This is a mirror of the Netatalk GitHub Wiki. Please visit the original page if you want to correct an error or contribute new contents.
Last updated 2024-10-20
