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.

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

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.

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!