Yelp » Tools »

yelp.m4

The yelp-tools package contains build utilities that help you build and install your help files according to the freedesktop.org help specification. The freedesktop.org help specification was jointly created by GNOME and KDE developers to create a single help system that all desktop environments use. To date, Yelp is the only implementation.

The build utilities are contained in a single file, yelp.m4. To use it, add the following to your configure.ac file:

```
YELP_HELP_INIT
```

You can also pass a space-separated list of options as the first argument to YELP_HELP_INIT:

```
YELP_HELP_INIT([options...])
```

The following options are currently recognized:

no-lc-media-links
- Normally, the build utilies create symlinks for localized media files when translators have not provided an actual localization. This means that copies of media files always exist in each locale's directory, even if there is no translation. Passing the no-lc-media-links option suppresses these symlinks.
  For normal images and videos, Yelp is able to look up files according to a document search path, so the symlinks are actually unnecessary. This has been true since at least Yelp 3.0. If you are only installing images and videos that are embedded in pages, use this option. If you use HELP_MEDIA for other types of files, such as source code or other files that get linked to, only use this option if you have verified that it works in production.
  Added in 3.12
no-lc-dist
- Normally, the build utilities dist the generated translated files, including the localized copies of HELP_FILES output by itstool and the stamp file used for tracking when the localized files were built. Using the no-lc-dist option makes these generated files not be included in the tarball. This reduces the size of the tarball, but increases the time it takes to build from the tarball.
  $/!\$ Note that currently, help.gnome.org does not use any sort of build system, and only uses files found in tarballs. If you use no-lc-dist, translations of your documents will not show up correctly on help.gnome.org or any other site that uses the same code.
  Added in 3.12

By default, the help directory is $PREFIX/help, and each language is installed to $PREFIX/help/$LANG/$HELP_ID/. The build utilities automatically provide a configure option --with-help-dir, allowing users to override the help directory.

The build utilities expect a layout that looks something like this:

help/
  Makefile.am
  C/
    help files...
    media/
      help media files...
  ll/
    ll.po
    media/
      help media files for ll...

There is a single Makefile.am file in the help directory that manages all translations. The help directory can have any name, or be arbitrarily deep. For projects with a single help document, it's common to simply use a top-level help directory.

The source files are expected to be in a directory called C. It's common to put images, videos, and other non-XML files in a subdirectory called media or figures. The actual name of the subdirectory doesn't matter, but examples on this page will use media.

Each translation has its own directory named according to the locale. That directory contains a PO file also named according to the locale. The name of the directory must match the base name of the PO file. For media files (those not translated using the PO files), translators add localized files using the same names and directory layout as the source files. If a media file does not need to be localized, you do not need to copy it. The build utilities take care of this automatically.

The Makefile.am file must start with the following line:

```
@YELP_HELP_RULES@
```

You can set the following variables:

HELP_ID
- The ID of the help document. This determines the install location, and will be referenced in the help: URIs used in your application. This variable is required.
HELP_POT
- A file name for a POT file to create when running make pot. This variable is optional. It defaults to ${HELP_ID}.pot. Note that make pot is not run as part of make. This is useful for Mallard page sets that are designed to merge into another document with the same HELP_ID. If make pot is used to generate a POT file for an external translation tool, that tool may expect POT file names to be globally unique.
HELP_FILES
- A space-separated list of the primary XML files. These files will be translated using the PO files and localized versions will be output when running make. This variable is appropriate for Mallard page files, top-level DocBook files, and any XML files that are included with XInclude. All files listed in HELP_FILES must be well-formed XML. List all files relative to the C directory.
  $/!\$ Because of the way yelp.m4 calls itstool, currently files in HELP_FILES must be directly in the C directory, not a subdirectory. If you use a subdirectory, the directory structure will not be reproduced in translations. See bug 690561.
HELP_EXTRA
- A space-separated list of files that are disted and installed for C, but are not in any way localized. This variable is appropriate for XML files that are included with SYSTEM entities and text files included with XInclude. These types of files are merged by default by itstool when creating PO files, so they are redundant in localizations. List all files relative to the C directory.
HELP_MEDIA
- A space-separated list of files that are disted and installed for C, and which translators may create localized copies of. If translators do not create localized copies, the build utilities automatically create symlinks to the C files on make install, unless you pass the no-lc-media-links option to YELP_HELP_INIT. This variable is appropriate for images, videos, and any external files that are linked to within the help. List all files relative to the C directory.
HELP_LINGUAS
- A space-separated list of locales that are enabled. The build utilities will only use translations listed in this variable.

The build utilities automatically handle make, make install, make uninstall, and make dist. Additionally, the following make targets are handled:

make check
- When running the standard make check target, all files in HELP_FILES are checked for well-formedness using xmllint. Note that make check does not automatically do validation against schemas.
make pot
- Create POT file using itstool from the files in HELP_FILES. The name of the POT file can be specified by the HELP_POT variable, and defaults to ${HELP_ID}.pot. This is not called as part of make all. However, some projects store the POT file in version control, even though it's auto-generated, so that it can easily be picked up by online translation tools. If you do this, it's a good idea to make the all target depends on pot.
make repo
- Updates all the languages' PO files using the latest sources. This is not called as part of make all.