Re: Move to XML, new converter to HTML etc

[Gregory Leblanc <gleblanc cu-portland edu>]

I'm going to try to reply just once, and catch most of the things that I
need to reply to, so bear with me if things get a little jumbled.  We
can split out to other threads if there's a lot of discussion on any of
these topics, but I don't really think there's that much to talk about.

On 11 Apr 2001 14:33:05 +0100, laszlo kovacs wrote:
> Hello,
> 
> It is quite important for me to have some kind of plan up to Gnome 2.0
> about the documentation processing and display related issues.
> 
> This is what I think is supposed to happen according to what has been
> discussed at GUADEC:
> 
> 1. Move docs to XML from DocBook SGML (I am a bit lost between the
> acronyms and various types of SGML and XML, but I hope it is obvious
> what I am talking about).

Right, current docs are written in DocBook SGML.  For the next release,
docs will be written using DocBook XML.  Same language, -very- slightly
different syntax, at least the way that we use it.  

> 2. Develop a new xml->html converter (instead of gnome-db2html2) based
> on libxml2 and libxslt.

This is already done, mostly.  Norman Walsh has written some DocBook XSL
stylesheets to transform DocBook XML into HTML.  We'll need a few
customizations to this, but it should be straight forward.

> libxslt needs XML as input.
> 
> I think we should have a plan for 1-3. My main problem is obviously 3.
> Technically Daniel's SGMLparser supplied for gnome-db2html2 (to turn the
> SGML stuff to valid XML) should be good for me to apply to docs and then
> implement all sorts of cool features with libxml2 and libxslt on top of
> it in Scrollkeeper. I looked into this and the SGML parser seems to have
> problems, one of the most important ones being that it does not resolve
> external entities (Laszlo assumes here that external entities are
> included SGML files in other SGML files). Considering that we move our
> docs to XML anyway soon and Sun's next official Gnome release will be
> 2.0 I really dont feel like trying to fix the SGML parser and then throw
> it out in a couple of weeks or months. Right now there are two people

My 0.02 DKK are that we should fix the DocBook parser, at the very least
for ScrollKeeper, since that is not GNOME specific.  We'll want to be
able use sk with, for example, LDP or FreeBSD DocBook SGML docs.  I
don't know how to go about rendering DocBook SGML docs, other than the
hack(s) that we currently have, so perhaps we'll just have to rely on
people to ship HTML versions of their docs if they're using SGML.

> How difficult it is to turn DocBook SGML docs to XML? Is it automatic or

Trivial for GNOME, since we've all been following the recomendation in
the Handbook (right?).  

> it will be done by hand? Do we have any idea how to develop the libxslt

It's really just a matter of changing the DTD, updating the header
(articleinfo changed between 3.x and 4.x of DocBook), and checking that
all tags are closed.  So, I guess some by hand, and some automatically.
> based converter and who will do it? The libxslt library contains

Norm Walsh has already written the converter, we'll just need to
customize it a little.  I don't know who'll do that (I would really like
to, but I'm sort of busy at the moment).

On 12 Apr 2001 05:25:00 -0400, Daniel Veillard wrote:
>  The things which need specific focus are:
>  1/ how do we store the XML Docbook DtD and XSL stylesheet (the bulk
>     of it should be shared with the KDE guys IMHO).

This isn't a GNOME issue, is it?  We shouldn't need to ship the DocBook
DTD, nor the base stylesheets.  We -DO- need to ship our customized
stylseheet.

>  2/ add a catalog support to the XSLT command line or library so
>     that formating docs don't go to the network to ftech those.

Erp, yes, that would be really nice.  One of these days I'm going to
figure out why the flame XML requires a URI instead of being able to
work with FPIs properly.

>  3/ customize if needed the default XSLT stylesheets from Norman Walsh
>     to give a Gnome look and feel (since XSLt has an import mechanism
>     this can still be done while sharing 95% of the default 
> stylesheets)

Yeah, this is definately one that we need to do, although it's a
"programming" project which we can take a few months on.  As soon as I
get my other project under way, I want to do this, unless somebody beats
me to it.  (not that I'll complain, I'll just have to find another
excuse to learn XSL).  

Ok, I think that's enough out of me, anybody know anything that I've
neglected to mention here?
    Greg