Re: Publishing HTML

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Fri, Jun 22, 2001 at 06:38:05PM +0100 or thereabouts, 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

The problem with this is that the appearance is going to vary, and
the reason is going to depend on several things. When I was getting
started, I would write something in DocBook, and then use db2html
(which calls jade to apply a particular stylesheet) and look at
the results in gnome-help-browser, in netscape, and in lynx. The same
HTML would render differently in each of those. Drastically so. And 
that was just to check the HTML from that stylesheet. Then I'd try 
db2ps to see how the printable version would come out, and the .ps
would be very different again. 

For example, say you refer to a URL in this way:
    <ulink url="http://www.gnome.org";>www.gnome.org</ulink>

The HTML version did what you'd expect: a clickable link to www.gnome.org
which appeared as "www.gnome.org". 
The PS version would come out as "www.gnome.org (http://www.gnome.org)".
Which is silly :) 

So I realised checking the HTML version wasn't always enough anyway.
And started referring to 
    <ulink url="http://www.gnome.org";>The GNOME website</ulink>
This of course came out as a clickable link labelled "The GNOME website"
on HTML, and "The GNOME website (http://www.gnome.org)" on PS, which
looked much better :) 

So that was the same stylesheet, producing HTML or PS versions. 

And of course, you can apply various stylesheets. The standard one
that came with the docbook tools produced HTML with a grey background.
Dave Mason tweaked it a bit so that HTML docs generated with his 
version of the stylesheet came with a nice white background. All 
the docs from Red Hat came with this nice white background; but if
you grabbed a Gnome tarball, you'd get the grey version. I always 
wanted to find a few others to try just to see how many ways you
could make the output appear. 

So whilst checking there's no dreadful foulups works if you just
generate a quick HTML version, you still don't entirely know how
it's going to come out, especially when there's multiple stylesheets
floating about. Quite how John's new renderer is going to affect
this, I don't know. Going on past history, I would bet that at least 
one person or group is going to tweak it. :) 

> 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.

I would in fact like to have HTML docs generated from what's in CVS
and on the gnome website. Something like 
http://www.gnu.org/manual/manual.html where you have a list and
each of the links goes to a page where you get a choice of formats. 
(eg http://www.gnu.org/manual/bash-2.02/bashref.html)

But we'd all need to commit "builds properly" docs so as not to
wreck scripts, and I wonder how much load it would add on the machine
to create a full set like that.

> 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!

I hate to admit this, but I'm a bit unclear what the idea is? To
have the docs on the web? Or to remove nautilus from the "generate
and view docs" process? 

I'm all for the first. And I think you can do the second by just
running the converter on its own. You certainly could with old
versions of it. I did it all the time. I couldn't build Nautilus
from CVS, but I could check out the converter and run that and view
the result. Haven't tried the new one yet, to my shame :))
 
Telsa