Re: jrb help: XML & HTML

[David Merrill <david lupercalia net>]

On Wed, Sep 05, 2001 at 10:58:53AM -0500, Dan Mueth wrote:
> 
> On 4 Sep 2001, Mikael Hallendal wrote:
> 
> > > Shipping HTML versions of XML docs which we ship...  The potential gain is
> > > that people gain the flexibility of using a help browser which does not
> > > render XML docs.  The main issue here is that Nautilus was painfully slow
> > > on slow machines in the past.  I do not know if all the recent speedups
> > > fix this problem.  The main problem with shipping both HTML and XML and
> > > supporting non-XML browsers is that the help API becomes more complicated.
> > > I think I described this in greater detail on this list a while back, but
> > > the short version is: When foo.xml is converted to HTML, you get a handful
> > > of HTML files with anchors.  Thus, you cannot merely specify a position in
> > > the doc by the (path, XMLfilename, XMLid)  triplet when calling
> > > gnome_help_foo(). You need to specify the HTML filename and anchor, which
> > > take the place of the XML filename and id but are different.  I believe we
> > > have four solutions:
> >
> > Perhas I misunderstood this but it isn't (XMLfilename, XMLid) that you
> > call gnome-help with, is it?
> > You call it with (DocumentName, SectionName) which is then looked up in
> > ScroolKeeper to a (Filename, tag) (where tag could be the name of an
> > HTML-anchor).
> 
> The GNOME 1.x help API explicitly referred to HTML documents by giving an
> HTML filename with anchor.  The simplest way to transition to to GNOME 2.x
> is to add new functions which behave similarly but refer to an XML
> file and id.
> 
> If we wanted to put ScrollKeeper in the middle, we would do so using a URI
> scheme which extends beyond GNOME and works with KDE, LDP, etc. docs.
> Then all our docs and apps would refer to other docs using this URI
> scheme, and ScrollKeeper could act to resolve these URI's (into file: or
> potentially http: or other).  I think this may be a really nice way to do
> things and would be within the scope of ScrollKeeper, but we aren't at
> this point yet and probably won't be in time for GNOME 2.  (Especially
> since the GNOME 2 platform is supposed to be frozen.) If people like this
> approach (or dislike it), speak up and we can decide whether this goes on
> our TODO list.

That sounds like the right approach. I'm working on a proof-of-concept
implementation in python that I'm calling ScrollServer, and it is
already serving the ScrollKeeper documents. I'm using the medusa web
application platform, but it could be moved to something else pretty
easily.

I expect I'll have something usable well within the 2.0 timeframe,
although it certainly won't be as far along as the standard help
browser. Still, it will allow a user to get to the help using lynx. In
fact, it *already* lets the user get to the scrollkeeper database with
lynx. Not bad for a day's hacking, huh? ;-) Especially since I've
never coded python before.

I still have lots of functionality to do, of course. All it does now
is present the TOC and process (and cache) sgml -> html which is then
served as well. But at least I will be able to work alongside the
other efforts and provide a way for people without a gui to still gain
the advantages of ScrollKeeper.

-- 
Dr. David C. Merrill                     http://www.lupercalia.net
Linux Documentation Project                   david lupercalia net
Collection Editor & Coordinator            http://www.linuxdoc.org

Free Dmitry Sklyarov!  http://www.freesklyarov.org
Washington DC Protests http://www.lupercalia.net/dmca