Work with Documentation

Documentation

Netatalk documentation is maintained in Markdown format, which is then transformed to other formats for publishing.

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 two parts: the *NIX manual pages in roff format and the html manual hosted on the website.

The sources that are to be transformed to roff man pages must be in standards compliant CommonMark syntax. Additionally, we exclusively use four space indentation to represent code blocks in man pages, and never fenced code blocks. This is to avoid a compatibility issue where cmark-gfm produces roff code not compatible with groff (namely the C font.)

With the manual meant for html publishing, we freely use GitHub Flavored Markdown (gfm), notably 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.

• English version: https://netatalk.github.io/netatalk
• Japanese version: https://netatalk.github.io/netatalk/ja

Localizations

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.

Translate to new languages

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

• Make sure cmark-gfm or pandoc 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!