Subject:
Re: Gnome Help 2.0
From:
Gregory Leblanc ####@####.####
Date:
17 Jul 2001 04:37:10 -0000
Message-Id: <995344369.9113.0.camel@peecee.linuxweasel.com>
On 17 Jul 2001 00:46:30 -0300, Jorge Luiz Godoy Filho wrote:
> On Mon, 16 Jul 2001, ####@####.#### wrote:
> > On Tue, Jul 17, 2001 at 12:05:36AM -0300, Jorge Luiz Godoy Filho
> > wrote:
> >> On Mon, 16 Jul 2001, ####@####.#### wrote:
> >> >
> >> > We're using xsl, so what I would need is a customization layer
> >> > for Norman Walsh's (fabulous) stylesheets.
> >>
> >> We, here, is the Gnome project?
> >
> > Eeek. Yeah, sorry. I'm the guy working on the stylesheet/help
> > rendering system for GNOME. Our plan is to use libxslt to render
> > docs directly from DocBook on the fly using customizations to Norman
> > Walsh's stylesheets.
>
> OK. :-)
> I've been subscribed to the gnome and gnome-doc mailing lists for more
> than a year now, but I've not been reading it for a long time... :-(
Too bad, they can be quite fun. :)
> I have some questions on that idea, and I don't know if you're the
> right person to ask. I'll ask it here but feel free to tell me to ask
> them to somebody else or at somewhere else.
Several GNOMErs are reading the LDP lists at this point, and I think
that there are a couple of KDE guys as well.
> 1. What are the advantages, to the end user, of having (DocBook) Gnome
> Documentation converted on the fly to something Gnome Help can
> read? Why not just generating HTML ('make docs') files and
> displaying them?
Oooh, we just talked about this a short while ago, let me fetch the link
to the archives. Ah, here's the start of the thread, it's worth
reading.
http://mail.gnome.org/archives/gnome-doc-list/2001-June/msg00031.html
> 1.1. How to locate DSSSL stylesheets? Or we'll be restricted only to
> Norman Walsh's default stylesheets? (Honestly, I think they
> aren't enough and always need some customization to reflect
> project decision -- such as TOC, TOC level, CSS stylesheets,
> admonitions images, new processing directives, etc.)
None of the DSSSL processing engines are fast enough to be used for
on-the-fly conversions. We'll be using XSL for transforming DocBook
into HTML for rendering. I certainly agree that customizations are
needed, since the GNOME customizations probably aren't appropraite for
the LDP docs, and vice-versa. I'm not sure how we'll find the
stylesheets, perhaps John can answer better than I.
> 2. Has somebody made measurement tests and performance tests with this
> conversion? Are these tests results available?
I think John Fleck has done some testing, as well as Dan York and Daniel
V (sorry, I can't spell in English, let alone French). Apparently the
slowest part of rendering DocBook into HTML is with the chunking code in
Norm's stylesheets. With that said, Daniel has processed the complete
sources to DocBook: The Definative Guide in approximately 15 minutes,
with chunking. I think this is about 400 HTML files, or 600 printed
pages. I have no idea what it takes for the smaller docs just yet.
> 3. Is there going to be some kind of cache? In what way that cache
> differs from previously generated files (as I've asked on 1)?
KDE is planning to cache documents, and perhaps even ship a pre-built
cache. I would love to be able to avoid this, but I don't have any hard
performance numbers just yet. See above discussion for some reasons why
shipping the HTML is sub-optimal.
> 4. How are XREFs treated between documents?
I haven't the foggiest notion, sorry.
> 5. If I have a URI in my document that points to a website, will my
> user be able to click on it and have it displayed? (LDP documents
> have lots of links of this kind)
Well, that depends on a lot of factors, but I would generally say "yes".
This assumes that the person reading the docs has net access, of course.
> 6. I have some other questions, but I need to think on them based on
> the answer from these previous questions. :-))
<grin />
> >> > Daniel Veillard has kindly added DocBook sgml support to libxslt,
> >> > so this also is backwards compatible to sgml docs.
> >>
> >> Cool!
> >
> > Yeah, we all collectively owe Daniel a great deal of beer, or at
> > very least love and adoration. :-)
>
> When he comes to Brasil --- specifically to Curitiba ---, I'll pay him
> some beer. :-)
I'll be sure to let him know. :)
> >> SGML documents with a customized DSSSL stylesheet.
> >>
> >> We'll also have a customized XSL stylesheet.
> >>
> >> And, on the resulting HTML, we apply some CSS.
> >
> > OK. We oughta be able to work with something along those lines.
>
> Greg Ferguson corrected me on that answer, but I think that the above
> answer is still valid for some other projects and several documents
> written in DocBook.
>
> The problem with XML StyleSheets can be easily solved through the use
> of the <?xml-stylesheet?> PI. But, as I've asked before, how are you
> planning to solve that for DSSSL stylesheets?
We're not, DSSSL is too slow to render on the fly. For documents where
we don't have a custom XSL stylesheet, we'll use the default from Norm
Walsh. Hope that helps,
Greg
