netatalk.io

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

Markdown

In the feature release following 4.1 (most likely 4.2) the documentation will have been transcoded to Markdown format. Namely, CommonMark for man pages, and GFM for the html manual (for the support for tables.)

All documentation is built by default, but can be controlled with the -Dwith-docs Meson option. To get the localized manual, enable the -Dwith-docs-l10n option. This requires the po4a library.

Localizations

The manual translations live under doc/po. The localized manual pages will be put under doc/translated by the build system.

Translate to new languages

In order to translate the Netatalk documentation into a new language, follow these steps.

• Make sure cmark-gfm and po4a are installed.

• Edit doc/po4a.cfg and add the language’s two letter code to the first line, e.g. [po4a_langs] ja sv for Japanese and Swedish.

• Edit doc/manual/_Sidebar.md and add the intra-lingual hyperlink to the top of the sidebar.

• Edit scripts/common.py and add the two letter code to the LOCALES list.

• Run the Meson build system with the -Dwith-docs-l10n=true flag. (Or run the po4a tool directly.)

• The blank po files for your language should have been created under docs/po. Edit these files with your favorite gettext compatible po editor. Note that you should only translate prose. Ignore paragraphs that consist only of code, commands, or terminal output. (We currently have no way to flag these as out of scope for localization, unfortunately.) Also, make sure that inline Markdown formatting is represented in your translation as well, for instance **foo** for bold text.

• Re-run the po4a tool (directly, or through the build system). Now the merged Markdown files should appear under docs/translated/{lang}. Validate the translations for completeness and accuracy.

• Create a branch and commit your work! We are looking forward to your PR!

If you find an untranslatable string, please file an issue ticket. Cheers!

Footnotes

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 2025-02-15