Need help to get started with Mallard

[Leonardo Ferreira Fontenelle]

I wrote an index page, mostly the same as the one in the Ten Minutes Tour, and I can't have it converted to a (x)html page. What else should I do?

$ cat index.page
<page xmlns="http://projectmallard.org/1.0/" type="guide" id="index">
<title>Referência Médica</title>
</page>
$ gnome-doc-tool xhtml index.page
Unmatched element: page
Unmatched element: title

For me it seems that the syntax is correct. Isn't gnome-doc-utils (0.18) recognizing it as a Mallard page? Do I need to set up autottool files and the GNOME help  directories hierarchy? I'd like to try Mallard outside software documentation...

Thanks in advance!

--
Leonardo Ferreira Fontenelle <leonardof@...>

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

[Paul Cutler-3]

Leonardo,  thanks for the email.

I'm not sure on the conversion, but can you try to validate the XML using:

xmllint --noout --xinclude --relaxng `pkg-config --variable malrng gnome-doc-utils` foo.page

And make sure it validates?  Shaun will know more about converting it to html than I do.

Paul

On Tue, Oct 27, 2009 at 8:00 PM, Leonardo Ferreira Fontenelle <leonardof@...> wrote:

I wrote an index page, mostly the same as the one in the Ten Minutes Tour, and I can't have it converted to a (x)html page. What else should I do?

$ cat index.page
<page xmlns="http://projectmallard.org/1.0/" type="guide" id="index">
<title>Referência Médica</title>
</page>
$ gnome-doc-tool xhtml index.page
Unmatched element: page
Unmatched element: title

For me it seems that the syntax is correct. Isn't gnome-doc-utils (0.18) recognizing it as a Mallard page? Do I need to set up autottool files and the GNOME help  directories hierarchy? I'd like to try Mallard outside software documentation...

Thanks in advance!

--
Leonardo Ferreira Fontenelle <leonardof@...>

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

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

[Leonardo Ferreira Fontenelle]

Em Ter, 2009-10-27 às 20:07 -0500, Paul Cutler escreveu:

Leonardo,  thanks for the email.

I'm not sure on the conversion, but can you try to validate the XML using:

xmllint --noout --xinclude --relaxng `pkg-config --variable malrng gnome-doc-utils` foo.page

And make sure it validates?  Shaun will know more about converting it to html than I do.

The suggested command confirmed that the pages are valid. Waiting for something about converting. Thanks anyway!

--
Leonardo Ferreira Fontenelle <leonardof@...>

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

[Shaun McCance-2]

On Tue, 2009-10-27 at 23:00 -0200, Leonardo Ferreira Fontenelle wrote:

> I wrote an index page, mostly the same as the one in the Ten Minutes
> Tour, and I can't have it converted to a (x)html page. What else
> should I do?
>
> $ cat index.page
> <page xmlns="http://projectmallard.org/1.0/" type="guide" id="index">
> <title>Referência Médica</title>
> </page>
> $ gnome-doc-tool xhtml index.page
> Unmatched element: page
> Unmatched element: title
>
> For me it seems that the syntax is correct. Isn't gnome-doc-utils
> (0.18) recognizing it as a Mallard page? Do I need to set up autottool
> files and the GNOME help  directories hierarchy? I'd like to try
> Mallard outside software documentation...

Unfortunately, I didn't get Mallard support into gnome-doc-tool
in gnome-doc-utils 0.18.  The stylesheets were added, and the
build magic was added, but not the quick-fire command line tool.

I've attached a quick Makefile you can use to build XHTML for
a Mallard document.  It doesn't need to be integrated into a
full build system.  Just drop it in the same directory as your
page files and type 'make'.

The stylesheets rely on a cache file being generated first, and
this Makefile will take care of that for you.  The format of the
cache file is probably going to change slightly, so be aware that
this Makefile may not work as-is with gnome-doc-utils 0.20.  (But
then, gnome-doc-tool should do the right thing in 0.20.)

--
Shaun


[Makefile]

---

pages=$(wildcard *.page)
htmls=$(patsubst %.page,%.xhtml,$(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) : %.xhtml : %.page
        xsltproc \
          --stringparam mal.cache.file `pwd`/index.cache \
          --param mal.chunk.chunk_top 1 \
          `pkg-config --variable mal2xhtml gnome-doc-utils` $<

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

---

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

[Leonardo Ferreira Fontenelle]

Em Qua, 2009-10-28 às 12:01 -0500, Shaun McCance escreveu:

On Tue, 2009-10-27 at 23:00 -0200, Leonardo Ferreira Fontenelle wrote:
> I wrote an index page, mostly the same as the one in the Ten Minutes
> Tour, and I can't have it converted to a (x)html page. What else
> should I do?
> 
> $ cat index.page
> <page xmlns="http://projectmallard.org/1.0/" type="guide" id="index">
> <title>Referência Médica</title>
> </page>
> $ gnome-doc-tool xhtml index.page
> Unmatched element: page
> Unmatched element: title
> 
> For me it seems that the syntax is correct. Isn't gnome-doc-utils
> (0.18) recognizing it as a Mallard page? Do I need to set up autottool
> files and the GNOME help  directories hierarchy? I'd like to try
> Mallard outside software documentation...

Unfortunately, I didn't get Mallard support into gnome-doc-tool
in gnome-doc-utils 0.18.  The stylesheets were added, and the
build magic was added, but not the quick-fire command line tool.

I've attached a quick Makefile you can use to build XHTML for
a Mallard document.  It doesn't need to be integrated into a
full build system.  Just drop it in the same directory as your
page files and type 'make'.

The stylesheets rely on a cache file being generated first, and
this Makefile will take care of that for you.  The format of the
cache file is probably going to change slightly, so be aware that
this Makefile may not work as-is with gnome-doc-utils 0.20.  (But
then, gnome-doc-tool should do the right thing in 0.20.)

Thank you, it worked very well. But I've got two pages, index.page and asma-cronica.page (in English: cronic-asthma.page), and the generated index.xhtml doesn't have any reference to asma-cronica.page, even if index.cache does have it. What am I missing?

$ head -n 3 asma-cronica.page
<page xmlns="http://projectmallard.org/1.0/" type="topic" id="asma-cronica">
  <info><link type="guide" xref="index" /></info>
  <title>Asma crônica</title>

--
Shaun

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

[Shaun McCance-2]

On Wed, 2009-10-28 at 19:14 -0200, Leonardo Ferreira Fontenelle wrote:

> Em Qua, 2009-10-28 às 12:01 -0500, Shaun McCance escreveu:
> > On Tue, 2009-10-27 at 23:00 -0200, Leonardo Ferreira Fontenelle wrote:
> > > I wrote an index page, mostly the same as the one in the Ten Minutes
> > > Tour, and I can't have it converted to a (x)html page. What else
> > > should I do?
> > >
> > > $ cat index.page
> > > <page xmlns="http://projectmallard.org/1.0/" type="guide" id="index">
> > > <title>Referência Médica</title>
> > > </page>
> > > $ gnome-doc-tool xhtml index.page
> > > Unmatched element: page
> > > Unmatched element: title
> > >
> > > For me it seems that the syntax is correct. Isn't gnome-doc-utils
> > > (0.18) recognizing it as a Mallard page? Do I need to set up autottool
> > > files and the GNOME help  directories hierarchy? I'd like to try
> > > Mallard outside software documentation...
> >
> > Unfortunately, I didn't get Mallard support into gnome-doc-tool
> > in gnome-doc-utils 0.18.  The stylesheets were added, and the
> > build magic was added, but not the quick-fire command line tool.
> >
> > I've attached a quick Makefile you can use to build XHTML for
> > a Mallard document.  It doesn't need to be integrated into a
> > full build system.  Just drop it in the same directory as your
> > page files and type 'make'.
> >
> > The stylesheets rely on a cache file being generated first, and
> > this Makefile will take care of that for you.  The format of the
> > cache file is probably going to change slightly, so be aware that
> > this Makefile may not work as-is with gnome-doc-utils 0.20.  (But
> > then, gnome-doc-tool should do the right thing in 0.20.)
> >
>
> Thank you, it worked very well. But I've got two pages, index.page and
> asma-cronica.page (in English: cronic-asthma.page), and the generated
> index.xhtml doesn't have any reference to asma-cronica.page, even if
> index.cache does have it. What am I missing?
>
> $ head -n 3 asma-cronica.page
> <page xmlns="http://projectmallard.org/1.0/" type="topic"
> id="asma-cronica">
>   <info><link type="guide" xref="index" /></info>
>   <title>Asma crônica</title>
>

Does index.page have type="guide"?

--
Shaun


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

[Leonardo Ferreira Fontenelle]

Em Qua, 2009-10-28 às 21:02 -0500, Shaun McCance escreveu:

On Wed, 2009-10-28 at 19:14 -0200, Leonardo Ferreira Fontenelle wrote:
> Em Qua, 2009-10-28 às 12:01 -0500, Shaun McCance escreveu: 
> > On Tue, 2009-10-27 at 23:00 -0200, Leonardo Ferreira Fontenelle wrote:
> > > I wrote an index page, mostly the same as the one in the Ten Minutes
> > > Tour, and I can't have it converted to a (x)html page. What else
> > > should I do?
> > > 
> > > $ cat index.page
> > > <page xmlns="http://projectmallard.org/1.0/" type="guide" id="index">
> > > <title>Referência Médica</title>
> > > </page>
> > > $ gnome-doc-tool xhtml index.page
> > > Unmatched element: page
> > > Unmatched element: title
> > > 
> > > For me it seems that the syntax is correct. Isn't gnome-doc-utils
> > > (0.18) recognizing it as a Mallard page? Do I need to set up autottool
> > > files and the GNOME help  directories hierarchy? I'd like to try
> > > Mallard outside software documentation...
> > 
> > Unfortunately, I didn't get Mallard support into gnome-doc-tool
> > in gnome-doc-utils 0.18.  The stylesheets were added, and the
> > build magic was added, but not the quick-fire command line tool.
> > 
> > I've attached a quick Makefile you can use to build XHTML for
> > a Mallard document.  It doesn't need to be integrated into a
> > full build system.  Just drop it in the same directory as your
> > page files and type 'make'.
> > 
> > The stylesheets rely on a cache file being generated first, and
> > this Makefile will take care of that for you.  The format of the
> > cache file is probably going to change slightly, so be aware that
> > this Makefile may not work as-is with gnome-doc-utils 0.20.  (But
> > then, gnome-doc-tool should do the right thing in 0.20.)
> > 
> 
> Thank you, it worked very well. But I've got two pages, index.page and
> asma-cronica.page (in English: cronic-asthma.page), and the generated
> index.xhtml doesn't have any reference to asma-cronica.page, even if
> index.cache does have it. What am I missing?
> 
> $ head -n 3 asma-cronica.page 
> <page xmlns="http://projectmallard.org/1.0/" type="topic"
> id="asma-cronica">
>   <info><link type="guide" xref="index" /></info>
>   <title>Asma crônica</title>
> 
Does index.page have type="guide"?

Yes (see in the first quoted email).

--
Leonardo Ferreira Fontenelle <leonardof@...>

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

[Shaun McCance-2]

On Thu, 2009-10-29 at 19:25 -0200, Leonardo Ferreira Fontenelle wrote:

> Em Qua, 2009-10-28 às 21:02 -0500, Shaun McCance escreveu:
> > On Wed, 2009-10-28 at 19:14 -0200, Leonardo Ferreira Fontenelle wrote:
> > > Em Qua, 2009-10-28 às 12:01 -0500, Shaun McCance escreveu:
> > > > On Tue, 2009-10-27 at 23:00 -0200, Leonardo Ferreira Fontenelle wrote:
> > > > > I wrote an index page, mostly the same as the one in the Ten Minutes
> > > > > Tour, and I can't have it converted to a (x)html page. What else
> > > > > should I do?
> > > > >
> > > > > $ cat index.page
> > > > > <page xmlns="http://projectmallard.org/1.0/" type="guide" id="index">
> > > > > <title>Referência Médica</title>
> > > > > </page>
> > > > > $ gnome-doc-tool xhtml index.page
> > > > > Unmatched element: page
> > > > > Unmatched element: title
> > > > >
> > > > > For me it seems that the syntax is correct. Isn't gnome-doc-utils
> > > > > (0.18) recognizing it as a Mallard page? Do I need to set up autottool
> > > > > files and the GNOME help  directories hierarchy? I'd like to try
> > > > > Mallard outside software documentation...
> > > >
> > > > Unfortunately, I didn't get Mallard support into gnome-doc-tool
> > > > in gnome-doc-utils 0.18.  The stylesheets were added, and the
> > > > build magic was added, but not the quick-fire command line tool.
> > > >
> > > > I've attached a quick Makefile you can use to build XHTML for
> > > > a Mallard document.  It doesn't need to be integrated into a
> > > > full build system.  Just drop it in the same directory as your
> > > > page files and type 'make'.
> > > >
> > > > The stylesheets rely on a cache file being generated first, and
> > > > this Makefile will take care of that for you.  The format of the
> > > > cache file is probably going to change slightly, so be aware that
> > > > this Makefile may not work as-is with gnome-doc-utils 0.20.  (But
> > > > then, gnome-doc-tool should do the right thing in 0.20.)
> > > >
> > >
> > > Thank you, it worked very well. But I've got two pages, index.page and
> > > asma-cronica.page (in English: cronic-asthma.page), and the generated
> > > index.xhtml doesn't have any reference to asma-cronica.page, even if
> > > index.cache does have it. What am I missing?
> > >
> > > $ head -n 3 asma-cronica.page
> > > <page xmlns="http://projectmallard.org/1.0/" type="topic"
> > > id="asma-cronica">
> > >   <info><link type="guide" xref="index" /></info>
> > >   <title>Asma crônica</title>
> > >
> > Does index.page have type="guide"?
> >
> Yes (see in the first quoted email).

Ah, right.  Sorry.

So I just tried this with your index.page and asma-cronica.page here,
closing the asma-cronica page after the title.  It worked as expected.
Can you send me those two files and the generated cache file?

--
Shaun


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

[Leonardo Ferreira Fontenelle]

Em Qui, 2009-10-29 às 16:51 -0500, Shaun McCance escreveu:

So I just tried this with your index.page and asma-cronica.page here,
closing the asma-cronica page after the title.  It worked as expected.
Can you send me those two files and the generated cache file?

Sure! Sent in private (unless anyone else wants to try).

--
Leonardo Ferreira Fontenelle <leonardof@...>

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

[Shaun McCance-2]

On Wed, 2009-10-28 at 19:14 -0200, Leonardo Ferreira Fontenelle wrote:

> Em Qua, 2009-10-28 às 12:01 -0500, Shaun McCance escreveu:
> > On Tue, 2009-10-27 at 23:00 -0200, Leonardo Ferreira Fontenelle wrote:
> > > I wrote an index page, mostly the same as the one in the Ten Minutes
> > > Tour, and I can't have it converted to a (x)html page. What else
> > > should I do?
> > >
> > > $ cat index.page
> > > <page xmlns="http://projectmallard.org/1.0/" type="guide" id="index">
> > > <title>Referência Médica</title>
> > > </page>
> > > $ gnome-doc-tool xhtml index.page
> > > Unmatched element: page
> > > Unmatched element: title
> > >
> > > For me it seems that the syntax is correct. Isn't gnome-doc-utils
> > > (0.18) recognizing it as a Mallard page? Do I need to set up autottool
> > > files and the GNOME help  directories hierarchy? I'd like to try
> > > Mallard outside software documentation...
> >
> > Unfortunately, I didn't get Mallard support into gnome-doc-tool
> > in gnome-doc-utils 0.18.  The stylesheets were added, and the
> > build magic was added, but not the quick-fire command line tool.
> >
> > I've attached a quick Makefile you can use to build XHTML for
> > a Mallard document.  It doesn't need to be integrated into a
> > full build system.  Just drop it in the same directory as your
> > page files and type 'make'.
> >
> > The stylesheets rely on a cache file being generated first, and
> > this Makefile will take care of that for you.  The format of the
> > cache file is probably going to change slightly, so be aware that
> > this Makefile may not work as-is with gnome-doc-utils 0.20.  (But
> > then, gnome-doc-tool should do the right thing in 0.20.)
> >
>
> Thank you, it worked very well. But I've got two pages, index.page and
> asma-cronica.page (in English: cronic-asthma.page), and the generated
> index.xhtml doesn't have any reference to asma-cronica.page, even if
> index.cache does have it. What am I missing?
>
> $ head -n 3 asma-cronica.page
> <page xmlns="http://projectmallard.org/1.0/" type="topic"
> id="asma-cronica">
>   <info><link type="guide" xref="index" /></info>
>   <title>Asma crônica</title>
>

For the benefit of the list, Leonardo and I figured this out on IRC.
For some reason, reading the cache file fails when there are non-ASCII
characters in the file name.

--
Shaun


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

[Leonardo Ferreira Fontenelle]

Em Seg, 2009-11-02 às 11:34 -0600, Shaun McCance escreveu:

For the benefit of the list, Leonardo and I figured this out on IRC.
For some reason, reading the cache file fails when there are non-ASCII
characters in the file name.

Thanks, Shaun, I was going to tell the list but you were faster :)

--
Leonardo Ferreira Fontenelle <leonardof@...>

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

[Leonardo Ferreira Fontenelle]

Em Seg, 2009-11-02 às 11:34 -0600, Shaun McCance escreveu:

On Wed, 2009-10-28 at 19:14 -0200, Leonardo Ferreira Fontenelle wrote:
> Em Qua, 2009-10-28 às 12:01 -0500, Shaun McCance escreveu:
> > 
> > I've attached a quick Makefile you can use to build XHTML for
> > a Mallard document.  It doesn't need to be integrated into a
> > full build system.  Just drop it in the same directory as your
> > page files and type 'make'.
> > 

I detected a funny behaviour in the Makefile. If you save a Mallard file as "abc.page" but set its id to "xyz", this will be the name of the generated (x)html file. Probably not harmful (I only discovered it because of a typo), but worth to be documented if the behaviour becomes part of gnome-doc-tool.

--
Leonardo Ferreira Fontenelle <leonardof@...>

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

[Shaun McCance-2]

On Tue, 2009-11-03 at 22:09 -0200, Leonardo Ferreira Fontenelle wrote:

> Em Seg, 2009-11-02 às 11:34 -0600, Shaun McCance escreveu:
> > On Wed, 2009-10-28 at 19:14 -0200, Leonardo Ferreira Fontenelle wrote:
> > > Em Qua, 2009-10-28 às 12:01 -0500, Shaun McCance escreveu:
> > > >
> > > > I've attached a quick Makefile you can use to build XHTML for
> > > > a Mallard document.  It doesn't need to be integrated into a
> > > > full build system.  Just drop it in the same directory as your
> > > > page files and type 'make'.
> > > >
>
> I detected a funny behaviour in the Makefile. If you save a Mallard
> file as "abc.page" but set its id to "xyz", this will be the name of
> the generated (x)html file. Probably not harmful (I only discovered it
> because of a typo), but worth to be documented if the behaviour
> becomes part of gnome-doc-tool.

Probably worth mentioning, yes.  Note that gnome-doc-tool
gets filenames from IDs for DocBook files.  And in Mallard,
filenames aren't really all that relevant.  (I have plans
to support multiple-page files, and for those, filenames
really can't mean anything.)

It is peculiar with the Makefile, though, because it does
assume the filenames match the IDs.  And this means that
typing 'make' over and over again will cause it to keep
trying to make that file.

--
Shaun


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