Re: generating html docs with gnome-doc-utils

[Stefan Kost <ensonic hora-obscura de>]

Hi Shaun,

sorry for the late reply. I run

  gnome-doc-tool html -o xhtml/ -c xhtml/style.css platform-overview.xml
in
  gnome-devel-docs/platform-overview/C

It basically does a good job. The generated files look similar to if I would
watch the xml in yelp. unfortunately the pictures for e.g. note-boxes are
missing and the style looks different too. Also the navigation is less optimal.
In yelp there is the navigation bar on top - in the generated pages I can only
go back and forth, no way to get to the top link again. It also creates a broken
link (which works in yelp). Any ideas? Should the outcome be the same?

Stefan


Shaun McCance wrote:
> 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
> 
>