You want to do use
for all your packages, since it would automate most of the
documentation build process, and it would enable translations using
PO files (with
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?).
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
After initial run, you'll end up with
into your package top source directory. You'll probably get warnings
about further steps you need to take (like adding
configure.ac). So, it's a good idea to do that right away: add call
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
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
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
<?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/*.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
To add new documents to your help directory, use
shaunize --new-document DOCUMENT.
for you. These are only templates, and you'll want to modify them
to suit your requirements.
Also, you should add
./help/Makefile.am (you may
need to create it), and
gnome-doc-utils is updated to
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.
To add new translations, simply put translated PO files into
Note that gnome-doc-utils doesn't handle figures correctly yet, so
they'll be missing from your tarballs generated with
dist, and won't be installed either.
Another problem is that *.omf files are not yet removed
make distclean call, so
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.