Re: Stylesheets [was: Re: [Nautilus-list] Re: Help API for GNOME 2.0]

[Malcolm Tredinnick <malcolm commsecure com au>]

On Sun, Jul 15, 2001 at 02:49:14PM -0600, John Fleck wrote:
> > On Sun, Jul 15, 2001 at 01:24:39PM -0500, Dan Mueth wrote:
> > > We haven't discussed how we should deal with stylesheets, so we should put
> > > a little thought into this.  What do we want?
> > > 
> > > (1) We use one stylesheet for all documents
> > > (2) Each group of docs (eg. GNOME docs, KDE docs, LDP docs) gets one
> > > stylesheet
> > > (3) Each document/package is able to specify and/or supply its own
> > > stylesheet.
> > > 
> > > I always thought we would at least have #2, so that GNOME docs could put a
> > > little footprint icon at the top and KDE docs could put their logo at the
> > > top if they wanted.  However, I could also imagine things getting really
> > > messy if we allowed a lot of configurability.

[...snip...]

> If #2, how would we test to see which stylesheet to use? File
> location? And what of files not in a predictable location? Fall back
> to a standard default stylesheet with no project-specific decorations?
> 
> It would be simpler to go with #1 and have any project-specific
> decorations specified in the doc. Can we do that?

My initial reaction to this is that it feels "icky", if you'll excuse
the complicated technical terms. :-)

What follows is a bit of a brain dump on my part. In case it comes
across the wrong way, I'm not just out to cause trouble or play Devil's
Advocate. I would like to see us do this correctly (or at least
extensibly) now, rather than having to redesign the whole thing again
for Gnome 3.0.

Let me outline my concerns and then propose a possible solution at the
end.

For each inline presentation instruction, the XSLT document will need to
know who to handle it for markup purposes. So you end up with a single
stylesheet that has to cover LDP, GNOME, KDE and everything beyond.
Trying to avoid this by using CDATA constructs seems a bit doomed, since
I can't see how you say things like "at the top of every page" and it is
also very hard when making an audio version for sight-impaired people
(to pick a single example).

My second concern is extensibility. Two years ago I hardly ever read GNU
info pages ... I hated the interface. When the GNOME help browser
included the ability to view info pages, I started using them a lot. I
consider myself an advanced user in Linux and GNOME areas, so there must
be other people who also avoid info pages via the standard text
interface. In the past, on IRC, I have pointed people to things like the
"make" info page for assistance and they've been quite thrilled to know
that they can use the help-browser to view them. So I don't think my
suspicions are entirely false. 

There is a point here somewhere (I'm getting to it)...

My understanding of the Scrollkeeper project is to provide consistent
indexing of _all_ the documents on my system. This will include info
pages, kernel docs, all of the above mentioned projects and probably
some we haven't heard of yet. Do we wish to provide a way to view these
documents? If so, we also need a way to use the right stylesheets for
them. I think they should all have seperate stylesheets, otherwise we
will have to continually update the "master" stylesheet and also have
constant debates about whether or not to add project X's style wishes to
our master. It is neither fair nor reasonable to expect that we can
shoe-horn all new projects into the existing categories.

Possible solution:

Make it is the responsibility of whatever application you are using to
display the help to choose an appropriate stylesheet. Even the document
author cannot always say what is correct (for example, there may be a
variety of text-to-speech transformations that can be done for the
sight-impaired -- that is where the displaying application comes into
play).

If you think about it, this is sort of where some of us have been
heading with previous posts in this thread, too: those browsers which
were HTML-only would do the conversion themselves, they wouldn't be
served up HTML pages on a platter.

Now, this means that each help browser needs to have a collection of
available stylesheets and apply the right one (or a default). For
example, GNOME help pages, info pages, KDE help pages, LDP pages, etc.
So we end up needing a catalog system again, a la DSSSL catalogs or
ScrollKeeper. I don't know enough about ScrollKeeper to know if it's
suitable for this or not.

Rereading this, I appear to have posed more problems than I've attempted
to solve. Hopefully my main concern comes through, however: how do we
handle other documents that don't fit into the boxes we already know
about? Or where do we draw the line at making new "boxes"?

Sorry to be a nuisance. :(

Cheers,
Malcolm

-- 
If it walks out of your refrigerator, LET IT GO!!