Migrating to GNOME Documentation Build Utilities

Many applications use an older method of including documentation. It is our intention that these applications switch over to gnome-doc-utils to provide a uniform method for building and installing documentation. The following instructions should help you to set up new documentation or port existing documentation to gnome-doc-utils.

2.1. Requirements

Make sure you're using recent gnome-common (from 2005-07-19 or later) if you're using gnome-autogen.sh, or call gnome-doc-prepare in your autogen.sh by hand.

2.2. Setting up help/Makefile.am

The standard location for documentation is in a subdir named help/ in your directory structure. This name is not mandatory, although it is recommended. There should also be a help/C/ subdirectory which contains the help document as document-name.xml.

In the help directory, create a file named Makefile.am. Define the following variables inside the file:

include $(top_srcdir)/gnome-doc-utils.make
dist-hook: doc-dist-hook

DOC_MODULE = document-name
DOC_ENTITIES = legal.xml
DOC_INCLUDES = filename.c
DOC_FIGURES = figures/main_window.png      \

DOC_LINGUAS = es sr uk
Here is a brief description of what each variable does:


The name of the help document to build. This is the filename without the .xml extension. You should have help/C/$DOC_MODULE.xml


List any files included in the help document using system entities.

Example: <!ENTITY SYSTEM "chapter1.xml">


List any files that are included with the Xinclude specification.


List all the figures that are referenced in the help document.


List all the language codes for the languages in which the document is currently translated.

2.3. Setting Up help/document-name.omf.in

GNOME Documentation Build Utilities require a template OMF file be installed at help/document-name.omf.in. This file contains a stripped down version of a Scrollkeeper OMF file. If you are porting documentation, you can modify your existing OMF file (and rename it) to meet these requirements.

PLEASE remember to change the documentation license if you are not using the GFDL. The GNOME documentation project does not endorse or recommend the use of this license without understanding the full implications of doing so.

Example 1Example of a OMF file template
<?xml version="1.0" standalone="no"?>
    <subject category="GNOME|Tutorials"/>
    <relation seriesid="b57e7e48-be78-11d6-85a3-d094906a987c"/>
    <rights type="GNU FDL" license.version="1.1" holder="Shaun McCance"/>

If you are porting documentation to gnome-doc-utils, use the the same seriesid attribute on the relation element as defined in your old OMF file. This will ensure that when the new documentation gets installed, it will get replace the older version of the document.

GNOME Documentation Build Utilities will create a document-name-C.omf and an additional document-name-<locale>.omf for each language code defined in the DOC_LINGUAS variable in Makefile.am. Depending on certain elements present in the help document, gnome-doc-utils will generate additional elements in the OMF file. For more information on this, please see the next section, Section 2 ― Migrating to GNOME Documentation Build Utilities.

Where the documentation shows up in Yelp depends on the category that you defined in the subject element. You can see a list of valid scrollkeeper categories at http://scrollkeeper.sourceforge.net/documentation/categories.html.

You can also get more information about what each element does by referring to the scrollkeeper docs.

2.4. Setting up help/C/document-name.xml

Create or move your help document to the location help/C/document-name.xml (replacing document-name with the actual document's name of course).

Then you will need to add the following elements/attributes to the help document so that gnome-doc-utils will be able to populate the autogenerated OMF files with the correct information. For more information about where these elements should appear in the document, you can refer to the excellent site http://www.docbook.org/tdg/en/html/.

<abstract role="description">This application is...</abstract>

Include this element in the <articleinfo> section of your help document. Gnome-doc-utils will use this information to create a <description> element in the generated OMF file.


Include this element (as well as firstname and surname elements as children) in the <authorgroup> section under the <articleinfo> element. Gnome-doc-utils will use this information to create the <creator> element in the generated OMF file.

<author>, <corpauthor>, <editor>, <othercredit>, or <publisher> with the attribute role="maintainer"

Include the attribute role="maintainer" on one of these elements so that gnome-docs-utils creates a <maintainer> element in the generated OMF file.

<title> element of the <article> or <articleinfo>

Gnome-doc-utils uses the contents of this element to create the <title> element in the generated OMF file.

<date> element in the last <revision> in your <revhistory>

Gnome-doc-utils uses the contents of this element to create the <date> element in the generated OMF file.

<revnumber> element in the last <revision> in your <revhistory>

Gnome-doc-utils uses the contents of this element to create the <version> element in the generated OMF file.

Example 2Example of DocBook file with required elements

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY appversion "1.0">
  <!ENTITY manrevision "1.0">
  <!ENTITY date "February 2006">
  <!ENTITY app "<application>My application</application>">
  <!ENTITY appname "My GNOME App">

<article id="index" lang="en">
    <title>&appname; Manual</title>
    <abstract role="description">
      <para>&appname; is a program that ...</para>
      <holder>Brent Smith</holder>
      <publishername> GNOME Documentation Project </publishername>


      <author role="maintainer">
        <affiliation><orgname>GNOME Documentation Project</orgname></affiliation>

        <revnumber>&appname; Manual &manrevision;</revnumber>

    <releaseinfo>This manual describes version &appversion; of &appname;</releaseinfo>

The example in Example 3 produces the following omf file, when using the document-name.omf.in file listed in Example 1.

Example 3OMF file autogenerated by gnome-doc-utils
<?xml version="1.0" encoding="utf-8"?>
    <creator>(Brent Smith)</creator>
    <maintainer>(Brent Smith)</maintainer>
    <title>My GNOME App Manual</title>
    <version identifier="My GNOME App Manual 1.0" date="2006-02-04"/>
    <subject category="GNOME|Tutorials"/>
      My GNOME App is a program that ...
    <format mime="" dtd="-//OASIS//DTD DocBook XML V4.1.2//EN"/>
    <identifier url="file:///opt/gnome2/share/gnome/help/test/C/test.xml"/>
    <language code="C"/>
    <relation seriesid="b57e7e48-be78-11d6-85a3-d094906a987c"/>
    <rights type="GNU FDL" license.version="1.1" holder="Shaun McCance"/>

2.5. Removing Leftover Files

If you are porting old documentation to gnome-doc-utils, then it is recommended that you remove old help/C/Makefile.am files, as well as any language specific OMF files, such as help/C/document-name-C.omf or help/<locale>/Makefile.am.

2.6. Adding New Files

If you don't already have one, create a m4 directory in the toplevel directory, and create a m4/.cvsignore file. Add both of these files to CVS.

Add a help/ChangeLog, analagous to po/ChangeLog, which is used to track translations and modifications to the help document. Also add this file to CVS.

Since gnome-doc-utils autogenerates .omf files for each locale for which the help document is translated, you will probably want to create and add a help/.cvsignore and add this file to CVS.

2.7. Modifying configure.ac

The following commands should be set in the configure.ac file.

  1. Add help/Makefile to AC_CONFIG_FILES (or AC_OUTPUT if you still use the old method)

2.8. Modifying the Toplevel Makefile.am

The following modifications should be made to the toplevel Makefile.am file.

  1. Add gnome-doc-utils.make to EXTRA_DIST.

  2. Add gnome-doc-utils.make to DISTCLEANFILES.

  3. Add --disable-scrollkeeper to DISTCHECK_CONFIGURE_FLAGS.

  4. Add m4 to EXTRA_DIST in the top-level Makefile.am

    You must remember to add m4 to EXTRA_DIST insite the top-level Makefile.am, otherwise the directory won't be added to the package and configure will fail (to catch this, you must do make distcheck after make check).

2.9. Modifying the .cvsignore files

Certain files are generated during the build process that you want CVS to ignore when creating diffs and doing other functions. To make CVS ignore these files:

  1. Add gnome-doc-utils.make to the top-level .cvsignore
  2. Add *.omf to the help/.cvsignore file

2.10. Testing

To test and see if everything works:

$ make && make check

2.11. Additional Steps

There are just a few more steps to follow to finish migrating to gnome-doc-utils:

  1. Add a gnome-doc-utils dependency for your module in the jhbuild moduleset.
  2. Migrate existing translations as described on GnomeDocUtilsTranslationMigration (or just ask translators to do that for their own languages, since this may be harder to do)
  3. Change status of your module on GnomeDocUtilsMigration (if applicable).

2.12. Let Us Know About it!

We would definitely like to know if you port your documentation to gnome-doc-utils, so please send an email to the following mailing lists if you have converted (or started) using gnome-doc-utils to manage your documentation.

Let gnome-i18n@gnome.org and gnome-doc-list@gnome.org know about it!