Re: generating html docs with gnome-doc-utils

[Shaun McCance <shaunm gnome org>]

On Wed, 2007-02-14 at 23:15 +0200, Stefan Kost wrote:
> hi,
> 
> I try to re-build html docs for gnome-devel-docs. The project uses
> gnome-doc-utils and I also managed to fix the build a bit. I have the latest
> gnome-doc-utils (0.9.2) installed.
> 
> First question - it adds --with-help-formats=FORMATS option to configure. What
> is valid here? --with-help-formats=html,pdf or --with-help-formats="html pdf".

It's a space-separated list, because that's the easiest
kind of list to process with the shell and autotools.

> Second question - how to get it to build html. There are xsltproc calls in
> gnome-doc-utils.make. But I faild to see how to invoke them.
> 
> The makefile has some problems (and there are commet inside the seem to support
> my doubts):
> > make
> Making all in platform-overview
> make[1]: Entering directory
> `/home/ensonic/projects/gnome-devel-docs/platform-overview'
> Makefile:573: warning: overriding commands for target `es/platform-overview.xhtml'
> Makefile:559: warning: ignoring old commands for target `es/platform-overview.xhtml'
> make[1]: Circular es/platform-overview.xhtml <- es/platform-overview.xhtml
> dependency dropped.
> if ! test -d es/; then mkdir es/; fi
> case "." in /*) sd=".";; *) sd="../.";; esac; \
>         if [ -f "C/apx-modules.xhtml" ]; then d="../"; else d="$sd/"; fi; \
>         (cd es/ && \
>           `which xml2po` -e -p \
>             "${d}es/es.po" \
>             "${d}C/apx-modules.xhtml" > apx-modules.xhtml.tmp && \
>             cp apx-modules.xhtml.tmp apx-modules.xhtml && rm -f
> apx-modules.xhtml.tmp)
> Error: cannot open file '.././C/apx-modules.xhtml'.
> make[1]: *** [es/apx-modules.xhtml] Error 1
> make[1]: Leaving directory
> `/home/ensonic/projects/gnome-devel-docs/platform-overview'
> make: *** [all-recursive] Error 1
> 
> Any ideas? If someone shares the wisdom, I promisse to get it into the docs.

I admit I haven't thoroughly tested the HTML stuff in
the gnome-doc-utils.make.  What we're seeing here is
completely screwy, and shouldn't be happening.

Basically, you're seeing gnome-doc-utils attempt to
use xml2po to create translated versions of the target
format (HTML), rather than the source format (DocBook).
The flow should go like this:

C/apx-modules.xml
  --xml2po--> es/apx-modules.xml
  --db2html--> es/apx-modules.xhtml

Instead, this looks like:

C/apx-modules.xml
  --db2html--> C/apx-modules.xhtml
  --xml2po--> es/apx-modules.xhtml

That's just completely broken.

Now, the intention of the help-formats option was to
allow people to build *and install* different formats,
with ScrollKeeper and Yelp being capable of handling
it all.  That's not quite the case, so that code is,
at best, a stub for things that could come.

If you're generating HTML for some purpose other than
installing it on the system (like, say, to put it on
the web), then you may be interested in the new tool
gnome-doc-tool that appeared in 0.9.  For a synopsis
of how to use it to generate HTML, run

  gnome-doc-tool html --help

I would like to make this sufficiently flexible to
make it the tool of choice for all our DocBook->HTML
needs.  So I'll gladly add any hooks we need to help
us make nicer web versions of our DocBook.

--
Shaun