netatalk.io

Work with Documentation

Documentation

Netatalk documentation is maintained in Markdown format, which is then transformed by the build system to other formats for publishing and packaging.

Before version 4.2, the documentation was authored in DocBook XSL format, which is worth noting for historical reasons.

Updating Documentation

The Netatalk documentation consists of three parts: the READMEs, the UNIX manual pages in roff format and the html manual hosted on the website.

The sources that are to be transformed to roff man pages (located under doc/manpages) must be in standards compliant CommonMark syntax.

With the manual meant for html publishing, we freely use GitHub Flavored Markdown (gfm), notably for the pipe tables.

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 Markdown sources for the documentation are included as part of the changeset in your PR.

Local html manual

The html manual can be built for the local file system, in which case only the core pages are transformed. They then can get installed to the /usr/local/share/doc or equivalent location, or included with binary packages.

The GitHub CI system will also publish this version of the manual to GitHub Pages. This can be handy for validating the look and feel of the generated html pages.

Localizations

Warning: The localization of gfm pipe tables may fail with older po4a versions. v0.73 is a known good version.

The man pages and html manual are localized with the po4a framework. The translations live under doc/po. The localized manual pages will be put under doc/translated by the build system.

Existing translations can be found in doc/po. The po4a toolsuite is required to refresh translations and generate the translated markdown target files.

With po4a installed, configure the netatalk source code with the -Dwith-docs-l10n=true flag. This will trigger the msgmerge of translations and the output of localized documentation into doc/translated.

For instance, a good workflow meson setup build -Dwith-docs-l10n=true --reconfigure after each time you edit the translations and commit the result.

Flagging new documentation files for localization

When adding new manual chapters or man pages, the file needs to be listed in doc/po4a.cfg in order for the po4a tool to pick up the new file for translation.

Once you run po4a again, the po files for the new documentation file will be generated under doc/po as usual.

Then, make sure that the build system scripts are updated to not just build the new documentation page, but also install the localized version.

Finally, the file needs to be listed in the index for the html manual. This is accomplished by editing doc/manual/_Sidebar.md and adding a hyperlink to the appropriate section.

Translate to new languages

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

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-05-31