Re: generating html docs with gnome-doc-utils

[Stefan Kost <ensonic hora-obscura de>]

Hi Shaun,

Thanks for your quick reply. The document in question is
http://svn.gnome.org/svn/gnome-devel-docs/trunk/platform-overview/C/

Shaun McCance wrote:
> On Fri, 2007-03-09 at 21:27 +0200, Stefan Kost wrote:
>> 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?
> 
> Automatic graphics like icons and watermarks still require
> some hand-tuning.  Basically, you'll need to copy icons into
> the output directory manually.  You can use the ones inside
> /usr/share/yelp/icons, but make sure to change the names to
> exclude the 'yelp-icon-' prefix.

I found the icons, but the xslt that gnome-doc-tool used did not produce boxes
that use them.

> There is an option in the XSLT for the base URL for these
> graphics, so you could point them all to one place.  But
> I haven't yet exposed that option in gnome-doc-tool.
>
For the future it would be cool to have all docs prerendered online. The one I
am dealing with is one that we only have online right now.
> 
> The navigation bar at the top of pages in Yelp is a Yelp
> extension to the XSLT.  I would like to move that code
> "upstream" into gnome-doc-utils.
> 
> As for the broken links, are they ghelp links?  Handling
> those for web builds has always been a pain, and we've
> never gotten it quite right.

Not at all. It generates a toc page named according the xml master doc, but the
first back-link assues index.xhtml.

Stefan