# GNOME Documentation Build Utilities

## Introduction

The GNOME Documentation Build Utilities were created to make it easier for application developers to include and create documentation in their releases.

There are several advantages to using gnome-doc-utils in your application:

1. Translation is made much easier through the use of xml2po, which generates standard `.po` files from docbook/xml.

2. OMF file creation is automated from a template file for all translated languages.

3. Installation of documentation is automated.

GNOME Documentation Build Utilities are named gnome-doc-utils on the GNOME CVS server, so we will refer to them in this manner throughout the rest of this document.

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

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

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

    DOC_LINGUAS = es sr uk

Here is a brief description of what each variable does:

DOC_MODULE

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

DOC_ENTITIES

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

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

DOC_INCLUDES

- List any files that are included with the Xinclude specification.

DOC_FIGURES

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

DOC_LINGUAS

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

### 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 of a OMF file template

    <?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>

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, settingup-document-name.xml.

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.

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

<author>...</author>

- 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 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">
      <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-omf-autogen produces the following omf file, when using the `document-name.omf.in` file listed in example-omf-template.

#### OMF file autogenerated by gnome-doc-utils

    <?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>

### 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`.`

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

### 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. `AC_CONFIG_MACRO_DIR`(`[m4]`)

3. `GNOME_DOC_INIT`

### 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`).

### 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

### Testing

To test and see if everything works:

    $ make && make check

### 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).

### 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!