Migrating to GNOME Documentation Build Utilities

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.

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      \
              figures/open_document.png

DOC_LINGUAS = es sr uk

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.

<?xml version="1.0" standalone="no"?>
<omf>
  <resource>
    <subject category="GNOME|Tutorials"/>
    <type>manual</type>
    <relation seriesid="b57e7e48-be78-11d6-85a3-d094906a987c"/>
    <rights type="GNU FDL" license.version="1.1" holder="Shaun McCance"/>
  </resource>
</omf>

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.

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/.

<?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">
  <articleinfo>
    <title>&appname; Manual</title>
    <abstract role="description">
      <para>&appname; is a program that ...</para>
    </abstract>
    <copyright>
      <year>2006</year>
      <holder>Brent Smith</holder>
    </copyright>
    <publisher>
      <publishername> GNOME Documentation Project </publishername>
    </publisher>

    &legal;

    <authorgroup>
      <author role="maintainer">
        <firstname>Brent</firstname>
        <surname>Smith</surname>
        <affiliation><orgname>GNOME Documentation Project</orgname></affiliation>
      </author>
    </authorgroup>

    <revhistory>
      <revision>
        <revnumber>&appname; Manual &manrevision;</revnumber>
        <date>2006-02-04</date>
      </revision>
    </revhistory>

    <releaseinfo>This manual describes version &appversion; of &appname;</releaseinfo>
  </articleinfo>
  <section>
    <title>Introduction</title>
    <para>Foo</para>
  </section>
</article>

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

<?xml version="1.0" encoding="utf-8"?>
<omf>
  <resource>
    <creator>(Brent Smith)</creator>
    <maintainer>(Brent Smith)</maintainer>
    <title>My GNOME App Manual</title>
    <date>2006-02-04</date>
    <version identifier="My GNOME App Manual 1.0" date="2006-02-04"/>
    <subject category="GNOME|Tutorials"/>
    <description>
      My GNOME App is a program that ...
    </description>
    <type>manual</type>
    <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"/>
  </resource>
</omf>

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.

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.

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

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

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:

To test and see if everything works:

$ make && make check

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

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!