How to get a valid HTML output from Mallard files?

[Mario Blättermann-3]

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.

Cheers,
Mario

<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">

  <info>
    <revision version="2.10" date="2005-06-01" status="final"/>

    <credit type="author">
      <name>Rob Bradford</name>
      <email>robster@...</email>
    </credit>
    <copyright>
      <year>2001-2005</year>
      <name>GNOME Documentation Project</name>
    </copyright>

    <license>Creative Commons Share Alike 3.0</license>
    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
  </info>

  <title>Tetravex manual</title>

  <p><app>Tetravex</app> is a simple puzzle game in which pieces have numbers
        on each side. The pieces must be positioned so that the same
        numbers touch each other, during which you are being timed.
        The times are then stored in a system-wide scoreboard.</p>
 
  <section id="intro" style="2column">
    <title>Introduction</title>
  </section>

  <section id="usage" style="2column">
    <title>Playing GNOME Tetravex</title>
  </section>


</page>

Introduction to GNOME Tetravex.

GNOME Tetravex is a simple puzzle where pieces must be positioned so that the same numbers are touching each other. Your game is timed, these times are stored in a system-wide scoreboard.

To run GNOME Tetravex, select GamesGnotravex from the Main Menu, or type gnotravex on the command line.

GNOME Tetravex is included in the gnome-games package, which is part of the GNOME desktop environment. This document describes version 2.30 of GNOME Tetravex.

How to play the game.

GNOME Tetravex is a simple puzzle game, this section covers how to play the game.

_______________________________________________
gnome-doc-list mailing list
gnome-doc-list@...
http://mail.gnome.org/mailman/listinfo/gnome-doc-list

[Shaun McCance-2]

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.

--
Shaun


[Makefile]

---

pages=$(wildcard *.page)
htmls=$(patsubst %.page,%.html,$(pages))

all: $(htmls) index.cache

index.cache : $(pages)
        echo '<cache xmlns="http://projectmallard.org/1.0/">' > $@.in
        for page in $(pages); do \
          echo "<page href='$$page'/>" >> $@.in; \
        done
        echo '</cache>' >> $@.in
        xsltproc `pkg-config --variable xsltdir gnome-doc-utils`/mallard/utils/mal2cache.xsl $@.in | xmllint --format - > $@
        rm $@.in

$(htmls) : index.cache
$(htmls) : %.html : %.page
        xsltproc \
          --stringparam mal.cache.file `pwd`/index.cache \
          --param mal.chunk.chunk_top 1 \
          `pkg-config --variable mal2html gnome-doc-utils` $<

.PHONY: clean
clean:
        rm index.cache *.html

---

_______________________________________________
gnome-doc-list mailing list
gnome-doc-list@...
http://mail.gnome.org/mailman/listinfo/gnome-doc-list

[Mario Blättermann-3]

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

_______________________________________________
gnome-doc-list mailing list
gnome-doc-list@...
http://mail.gnome.org/mailman/listinfo/gnome-doc-list

[Shaun McCance-2]

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


_______________________________________________
gnome-doc-list mailing list
gnome-doc-list@...
http://mail.gnome.org/mailman/listinfo/gnome-doc-list