Documentation build plans for 3.2

[Shaun McCance <shaunm gnome org>]

Hi all,

I've been working on a replacement for the documentation build tools
in gnome-doc-utils. I believe they're ready for 3.2. There are two
packages you'll need: itstool and yelp-tools.

http://files.itstool.org/itstool/
http://ftp.gnome.org/pub/gnome/sources/yelp-tools

This is the last step in my splitting up of gnome-doc-utils, so that
package is now completely deprecated. I'll be porting things to the
new tools incrementally. We don't have to get everything in one go.

See my blog posts for the advantages of itstool:
http://blogs.gnome.org/shaunm/tag/its/

yelp-tools contains a single m4 file, which gets slurped into your
aclocal.m4 file. No more extra .make file to dist. It only installs
to the proposed freedesktop.org help system.

http://lists.freedesktop.org/archives/xdg/2010-April/011462.html

This means we should change help button targets to the new URI scheme.
I'll probably add a ghelp compatibility hook into Yelp, to be safe.

On my system, building gnome-devel-docs went from ~14 minutes with
gnome-doc-utils to ~2 minutes with yelp-tools. So, big win if you
roll releases with lots of document translations.

In terms of dependencies, you only need to have yelp-tools installed
to build from git. You do need itstool installed to build either way.

Also, yelp-tools has some command-line tools: yelp-build, yelp-check,
and yelp-new. If you write docs, you might find these useful.

I've tried to be careful about portability, but at the end of the day,
all my computers have GNU utilities, so I might have screwed something
up. Please let me know if there are problems on non-GNU systems.

Thanks,
Shaun