Re: How to get a valid HTML output from Mallard files?

[Mario Blättermann <mariobl gnome org>]

Am Sonntag, den 01.11.2009, 20:19 -0600 schrieb Shaun McCance:
> On Sun, 2009-11-01 at 00:47 +0100, Mario Blättermann wrote:
> > Hi,
> > I've played a bit with Mallard. The Tetravex manual seems to be a good
> > test area. I have created three *.page files and tried to convert them
> > to HTML with the following commands:
> > 
> > xsltproc /usr/share/xml/gnome/xslt/mallard/html/mal2html.xsl index.page
> > > index.html
> > 
> > xsltproc /usr/share/xml/gnome/xslt/mallard/html/mal2html.xsl
> > introduction.page > introduction.html
> > 
> > xsltproc /usr/share/xml/gnome/xslt/mallard/html/mal2html.xsl usage.page
> > > usage.html
> > 
> > As a result I've got three files named as expected. But when I try to
> > open index.html, there only appears the content of index.page, and no
> > links to the subpages are provided. Seems that the normal xsltproc
> > doesn't work here. Is there a universal command to get a matching HTML
> > structure from multiple Mallard pages?
> > 
> > I'm using Fedora 11 (with an upgraded gnome-doc-utils package v0.18),
> > that's why I cannot view the Mallard pages directly with Yelp.
> 
> Hi Mario,
> 
> You have to generate a cache file first, which gets passed
> to each xsltproc call.  In the next stable version of g-d-u,
> I'll have gnome-doc-tool able to do this automatically, but
> right now it has to be generated by hand.
> 
> I've attached a simple Makefile you can drop into a directory
> containing Mallard page files.  You don't have to plug this
> into a full build system.  Just type 'make'.
> 
> The format of the cache files is probably going to change a
> bit in 0.18.  But with 0.18, you should be able to drop this
> and just use gnome-doc-tool instead.

OK, works fine. Thanks for your help. You should add this Makefile to
the Mallard docs. It's a good way to validate the written *.page files
without having a full environment of the appropriate application. But if
a already have 0.18 installed, how I have to call gnome-doc-tool?

I have translated the Mallard docs to German (currently still
incomplete), that's why I have some (virtual) experience with it. Due to
the fact that Mallard will be the default format for GNOME v3, I could
help you to migrate some manuals. Some modules are still untranslatable,
e.g. Gnumeric, Dia, Genius, Planner, GNOME Pilot, or Gok, in the meaning
of the g-d-u workflow. These should be migrated anyway before
implementing the g-d-u stuff, to prevent translators from wasting their
time. I've seen in the Empathy manual, that such a migration doesn't
keep really much of the old content.

Well, I'm not a native English speaker, and write a good technical
documentation is a difficult task. But I could make a 1:1 copy from the
existing DocBook content, and an experienced doc writer could review it,
to have it more topic-based and to make sure that the somewhat old
content is still valid. What do you think?

Another question: Why do we have the legal notices still in DocBook/XML?
I was a bit surprised that I couldn't find a section such as
"Information about this document" in the document view at
library.gnome.org (currently, in the Empathy and Mallard manuals only).
The translatable strings from legal.xml doesn't appear anywhere. Is it
intentional to hide the legal notices?

Cheers,
Mario