Build system integration
Autotools integration with yelp.m4
yelp‑tools provides comprehensive integration with Autotools build systems. To integrate with an existing project using Autotools, add the following line to configure.ac:
YELP_HELP_INIT
This adds several checks for tools that are used to build and transform Mallard documentation. Verify that the checks succeeded by looking for the following lines in the output from configure:
checking whether ln -s works... yes checking for itstool... itstool checking for xmllint... xmllint
Add build rules for Mallard documentation
To use the integration once the configure checks are in place and have succeeded, you need to add some build rules to a Makefile.am in your project, traditionally help/Makefile.am. A simple Makefile.am for a project with one page called index.page is shown below:
@YELP_HELP_RULES@ HELP_ID = myproject HELP_FILES = index.page HELP_MEDIA = media/logo.png
The HELP_ID should match the tarball name of the project, which is usually set in configure.ac. It controls the installation directory, which by default is /usr/share/help/LOCALE/HELP_ID. In this case, the index.page file should be placed in a subdirectory called C, which has a special meaning of having no associated localization. Conventionally, the C locale is understood to be English language.
If you are using images in your documentation, listed after HELP_MEDIA, they must also be inside the C subdirectory and are normally inside a dedicated media directory.
Remember that when adding a new Makefile.am to a project, it must also be added to AC_CONFIG_FILES in configure.ac:
AC_CONFIG_FILES([Makefile.am help/Makefile.am])
Finally, the help directory should be added to the toplevel Makefile.am:
SUBDIRS = help
This simple example already has some quite useful automation. The files listed in HELP_FILES and HELP_MEDIA are installed to the installation directory during make install. Be careful that any files which are transcluded with XInclude are also listed in HELP_FILES, as otherwise those files will not be installed! During make check, the files listed in HELP_FILES are validated against the Mallard schema with yelp‑check validate, so that any tarball release created with make distcheck will have valid documentation included.
Verify the Makefile.am changes by running make install and make check, and checking the output to see if Mallard pages were installed and validated:
$ make install install -m 644 C/index.page /usr/share/help/C/myproject/index.page
$ make check xmllint --noout --noent --path C --xinclude C/index.page
Translations
Mallard documents are translated with itstool and portable object (PO) files, which are a standard way of translating messages on Unix-like systems. Fortunately, integration with yelp.m4 hides much of the underlying complexity of the tools. For a project already using the build rules from yelp‑tools, change the directory to where the Makefile.am containing @YELP_HELP_RULES@ is located and run make pot:
$ cd help $ make pot
This takes the list of Mallard pages in HELP_FILES, extracts the translatable strings and merges them into a PO template (POT) file which will be named HELP_ID.pot, where HELP_ID is the name of the installation directory set with HELP_ID. The POT file contains a list of translatable strings combined with information about the location of the string in files and any comments which the help author may have added.
Integrating translations to the build system
Once a PO file has been created for a particular locale from the template, the PO file can be added to the build system so that the translated documentation can be installed and validated just like other Mallard pages.
The PO file should be named after the locale, formed by combining the two-letter ISO 639 language code with the two-letter ISO 3166 country code and an underscore, for example en_GB for English spoken in Great Britain. Create a directory for the locale, and move the POT file into that directory:
$ mkdir help/en_GB $ mv myproject.pot help/en_GB/en_GB.po
Once the PO file is in the correct location, add the following line to help/Makefile.am:
HELP_LINGUAS = en_GB
This integrates the British English language translation with the yelp.m4 build process, so that the translations from the PO file are used to create translated Mallard pages during the make process. As with the basic integration, the translated pages are validated during make check and installed in the install directory during make install.
Verify the Makefile.am changes by running make install and make check, and checking the output to see if Mallard pages were installed and validated:
$ make install install -m 644 C/index.page /usr/share/help/C/myproject/index.page install -m 644 C/index.page /usr/share/help/en_GB/myproject/index.page
$ make check xmllint --noout --noent --path C --xinclude C/index.page xmllint --noout --noent --path en_GB --xinclude en_GB/index.page
An important concern when translating Mallard documentation is that a translation can fail to validate, and this will cause make check to fail with an error.