Shaunizing packages

Preparing modules to use new gnome-doc-utils build system

Introduction

You want to do use gnome-doc-utils for all your packages, since it would automate most of the documentation build process, and it would enable translations using PO files (with xml2po from gnome-doc-utils being used).

The steps slightly differ between creating new help documents for a package using gnome-doc-utils, or for porting old documentation to gnome-doc-utils.

These are only preliminary instructions; they will probably change (anyone volunteering to switch this over to DocBook, fix any remaining gnome-doc-utils issues [see below for caveats], etc?).

Common steps

In each of cases, you start out with cd'ing into your package root directory, and running shaunize script provided with gnome-doc-utils. In Gnome projects, shaunize would probably be run from autogen.sh scripts. If you don't have this script, look at caveats below.

After initial run, you'll end up with gnome-doc-utils.make linked into your package top source directory. You'll probably get warnings about further steps you need to take (like adding GNOME_DOC_INIT to configure.ac). So, it's a good idea to do that right away: add call to GNOME_DOC_INIT into configure.ac (or configure.in).

Porting your documentation

Now, if you already have some documentation for your package, you want to switch that to using gnome-doc-utils. For the purposes of demonstrating the procedure, we'll assume that your documentation sits in $(top_srcdir)/help/.

If you anticipate to have more than one document in your package in the future, it would be wise to switch to directory layout Shaun proposes:

  $(top_srcdir)/help/document1/C/
  $(top_srcdir)/help/document2/C/
  ...

OTOH, if you want to keep CVS history, you'll probably want to keep your directory layout as it is. The only difference is in a moving step (mkdir help/document1 && mv help/* help/document1).

Now, you want to modify your help/Makefile.am to use gnome-doc-utils.make. You'll should end up with the following contents:

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

DOC_MODULE = document-name
DOC_INCLUDES = 

DOC_LINGUAS = 

Next, you want to put a template .OMF file for gnome-doc-utils to use to build all other OMF files (for translations and C locale). You should reuse your help/C/document-name.omf to create help/document-name.omf.in. For gnome-hello, I ended up with the following:

<?xml version="1.0" standalone="no"?>
<omf>
  <resource>
    <subject category="GNOME|Tutorials"/>
    <type>manual</type>
    <relation seriesid="b57e7e48-be78-11d6-85a3-d094906a987c"/>
  </resource>
</omf>

Note that all the other fields are populated by gnome-doc-utils based on the DocBook file itself, so no need to worry about that (what you actually care about here is category, and seriesid, which should be the same for all revisions of your document).

Now, you may remove any leftover build system files, such as help/C/Makefile.am, help/C/*.omf etc, and remove any of these from AC_OUTPUT (in your configure.ac). Be sure to also add gnome-doc-utils.make to your top-level DISTCLEAN_FILES.

Starting from scratch

To add new documents to your help directory, use shaunize --new-document DOCUMENT.

This will create ./help/DOCUMENT/Makefile.am, ./help/DOCUMENT/DOCUMENT.omf.in and ./help/DOCUMENT/C/DOCUMENT.xml for you. These are only templates, and you'll want to modify them to suit your requirements.

Also, you should add DOCUMENT to SUBDIRS in ./help/Makefile.am (you may need to create it), and add ./help/DOCUMENT/Makefile to AC_OUTPUT call.

Until gnome-doc-utils is updated to include shaunize script and needed template files, you may grab all of them from kvota.net/hacks/shaunize/, and manually copy them into your project directories.

Adding new translations

To add new translations, simply put translated PO files into help/lang/lang.po, and add lang to DOC_LINGUAS in help/Makefile.am.

Caveats

Note that gnome-doc-utils doesn't handle figures correctly yet, so they'll be missing from your tarballs generated with make dist, and won't be installed either.

Another problem is that *.omf files are not yet removed with make distclean call, so make distcheck will probably fail for you.

If you don't have "shaunize" script (since your gnome-doc-utils version might not yet integrate it), you may create it with the following contents:

#!/bin/sh
if [ ! -f gnome-doc-utils.make ]; then
   ln -s "`pkg-config --variable=datadir gnome-doc-utils`/gnome-doc-utils/gnome-doc-utils.make"
fi

This will simply symlink gnome-doc-utils.make into your source directory, so you could make use of it in your Makefiles. You won't get the templates for adding new documents.