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.
You can also use something like dblatex 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.
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-05-09
