Re: Publishing HTML

[John Fleck <jfleck inkstain net>]

On Fri, Jun 22, 2001 at 06:38:05PM +0100, Colm Smyth wrote:
> Hi!
> 
> I was chatting with Laszlo Kovacs about scrollkeeper and he mentioned
> that some people had a few good reasons for publishing the GNOME
> documentation as SGML, to be converted on the fly to HTML by Nautilus.
> 
> I've written a little documentation and it's generally been my
> experience that I wanted to see what the end output would look
> like because no documentation tool-set is WYSIWYG. It would seem
> that the best way to achieve this would be for the doc writers
> to publish their documentation as SGML to GNOME CVS and for a
> background process to convert these to HTML where they could
> be viewed (and verified) directly on the GNOME web site.
> 
> The other benefit is that Nautilus doesn't get slowed down
> doing conversion on the fly (although I've heard that this
> is pretty fast, it's not a no-op!).
> 
> Maybe one of the "old hands" on the GNOME documentation project
> could help me to understand why this isn't a good idea!
> 

Colm -

This is a terrific question. I've invested a lot of intellectual
capital over the last year on the render-on-the-fly systems, and I
sometimes wonder myself why we're doing it. The decisions were really
made long ago, and have a certain unquestioned momentum that is
probably worth questioning.

I see two main advantages, one in terms of the quality of
documentation we can provide for users and one in terms of ease of
documentation preparation for developers.

First, the users. The dream is that, by rooting our documentation in
sgml/xml, we can make our documentation smarter. In its native
DocBook, documentation is essentially like structured data. Things
like cross-linking to other documents, building glossaries, building
various kinds of flexible indexing tools, having smart "card
catalogue" systems like ScrollKeeper are possible with sgml/xml in
ways they would not with html, which despite its origins is, for all
practical purposes, a display language. This stuff is even easier and
more powerful once we switch to xml, with the power xslt gives us to
do these sorts of things.

This is all very hypothetical right now, and I worry that we are (I
am?) spending too much time on implementing the basic
rendering/display technology and not enough time working on adding the
resulting features this enables. But that's probably a topic for
another thread. :-)

Second, the developers. Having and operating the sgml->html tool chain
has been an ongoing difficulty for the GNOME community. It's just
plain hard. I realize we should not be doing things for the
convenience of developers - we should be thinking about users. But if
documentation is not easy for developers, then good documenation is
less likely to be done. So anything we can do to make documentation
easier for developers benefits users.

As for the computational overhead of generating these things on the
fly, I'm open to a discussion. It's not free, there is a time
penalty. It's not nearly as great as the other time penalties we're
paying using Nautilus to display our docs (mozilla being the primary
one), but it is there.

A technical antidote we've been looking at is some sort of caching
system, so the xslt processing on a doc only has to be done once. KDE
is working on something along these lines.

I'm heavily invested in direct rendering, so it's up to someone more
open-minded than me to jump into the discussion and argue in favor of
static html solely on this performance issue. Maybe some sort of
"pre-caching" at build time or something.

As for WYSIWYG display when you're writing a doc, the direct rendering
systems actually do a much better job. Used to be you had to run jade
to make html to look at. Now, you can look at docs directly in
Nautilus as you're working on them. The current gnome-db2html2 is a
little quirky for this, but its replacement, gnome-db2html3, is quite
robust for this task right now. I use it regularly in this mode.

Cheers,
-- 
John Fleck
jfleck inkstain net (h), http://www.inkstain.net/fleck/