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

[Shaun McCance <shaunm gnome org>]

On Mon, 2009-11-02 at 17:50 +0100, Mario Blättermann wrote:
> 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'm sorry.  My brain seems to have stopped functioning.  The
current version is 0.18.  Mallard support in gnome-doc-tool
will be in the *next* stable version, 0.20.  Sorry for the
confusion.

> 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?

One thing we've talked about is being more collaborative with
the writing process.  People who can provide information should
be able to provide information.  People who are good at content
organization should be able to organize content.  And people
who puts words to people well should be able to write.

So if a non-native English speaker knows a lot about a program,
and he's skilled at putting that information into a usable form,
then it would be crazy for us to turn down his skills just because
he makes a silly language mistake like writing "it gives" instead
of "there is". ;-)

> 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?

I don't think it's necessary (or useful) to have legal notices
about the software in the help.  As for notes about the help
(including stuff like credits), I punted on that feature for
2.28.  It's harder (on my end) with Mallard, because all that
information is per-page, not per-document.

--
Shaun