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

[John Fleck <jfleck inkstain net>]

Folks -

I think we're making this too complicated.

First of all, for Malcolm, we're talking here about stylesheets to
render DocBook docs, so for better or worse, info files or man pages
or straight html docs are not part of this discussion. Not that we
shouldn't talk about that (I'd love it if someone were maintaining and
thinking about info2html and man2html and how they fit into all of
this, but no one is right now), but that's a separate issue.

Malcolm wrote:

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

(My hope is that by generating html and passing that to a
text-to-speech browser, we'll be handling the accessibility issue. If
we need to write a special stylesheet for that, I think that's *real*
important and I'll do it.) 

> 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 disagree with this approach. I think our core system needs to be
able to generate displayable html, then hand that off to whatever
browser the user chooses. (Sorry if I'm repeating myself here.) Having
each browser maintain its own collection of stylesheets and xsl
rendering engine seems like wasteful duplication. If someone wants to
write their own DocBook->display rendering goober, nothing's stopping
them, but why should they have to? 

And the thing that worries me most in the above is Malcolm's "etc" at
the end of his list of different stylesheets. Who will be responsible
for maintaining what could be a proliferation of stylesheets? If it
clearly seems as though we will have three main categories of docs -
GNOME, KDE and LDP - then I can see maintaining three variant
stylesheets.

On Sun, Jul 15, 2001 at 08:42:29PM -0500, Dan Mueth wrote:
> 
> Wherever the code is placed, the result would be what Malcolm suggests:
> The document+OMF specifies a stylesheet by name and then a catalog is used
> to register and look up stylesheets.
> 

What about docs that don't specify a stylesheet? What about docs that
specify a stylesheet that isn't installed? We can come up with
solutions to test for and deal with these situations, but I think
we're adding needless layers of complexity. And we're asking non-GNOME
people to do more special stuff so we can properly handle their docs.

I'm uncomfortable with OMF specifying stylesheet information that will
be very GNOME-specific. I'm likewise uncomfortable with the docs
themselves specifying GNOME-specific stylesheet information. We're
drifting away from the generic-ness of DocBook, which is its virtue.

I'd like to come up with a more simple test to determine which of the
three it is, and then apply the appropriate stylesheet. If it's not
any of them, then use a fourth generic stylesheet.

> What do people think about this?
> 
> If, as Daniel and John suggest, the stylesheets are fairly standard and
> have only superficial differences then we should be fine.  If the
> stylesheets changed so much that the way documents are broken into pages
> changes then we'd have to make sure that the TOC, indexing, etc is not
> broken.  I think we should be fine though, since a given document will
> always be processed (indexed, displayed, TOC extracted) with the same
> stylesheet.
> 

If all we're dealing with is decorations at the top, or possibly even
page-by-page header and footer information, the differences indeed
should be superficial.

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