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

0 views
Skip to first unread message

Dan Mueth

unread,
Jul 15, 2001, 2:35:17 PM7/15/01
to

On 14 Jul 2001, Jonathan Blandford wrote:

> John Fleck <jfl...@inkstain.net> writes:
>
> > Folks -
> >
> > Much to comment on here. I'll try to incorporate responses to most of
> > the thread, but I'll break some bits out into separate
> > missives. Thanks to Dan for thinking this through and getting us
> > started.
> >
> > On Tue, Jul 10, 2001 at 04:34:52PM -0500, Dan Mueth wrote:
> > >
> > > The main question we need to answer is whether we want to support
> > > HTML-only help browsers. If we can assume that the only help browsers
> > > people want to run can handle SGML/XML (ie. Nautilus), then we can do
> > > something simple like:
> > >
> > > gnome_help_display(path, name, linkid)
> > > path = path in $PREFIX/share/gnome/help (as GNOME 1.x)
> > > name = doc file name, without extension (it will search
> > > for .xml, then for .sgml)
> >
> > If we're using some sort of a caching system to speed up rendering (as
> > our KDE friends have decided to do), it also needs to search for a
> > cached copy of a rendered doc first before looking for xml and
> > sgml. (This may be especially important for the big docs David Merrill
> > has discussed. I think it makes sense to match our caching system up
> > with KDE's so we'll be able to easily read one another's cached docs.)
>
> Do you cache chunking data or HTML? Would we need to share stylesheets.

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.

Thoughts?

Dan


_______________________________________________
gnome-doc-list mailing list
gnome-d...@gnome.org
http://mail.gnome.org/mailman/listinfo/gnome-doc-list

Daniel Veillard

unread,
Jul 15, 2001, 2:51:15 PM7/15/01
to
On Sun, Jul 15, 2001 at 01:24:39PM -0500, Dan Mueth wrote:
> > Do you cache chunking data or HTML? Would we need to share stylesheets.
>
> 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.
>
> Thoughts?

Seems to me that you forget the very important point that most
stylesheets are based on an existing core which is reused by all
different styles (only part of the default formatting are overriden
to provide a given style). Most of the XSLT code is Norm Walsh one and
MUST be shared. Some extensions on top of it may be shared but will be
relatively small in comparison.

Daniel

--
Daniel Veillard | Red Hat Network http://redhat.com/products/network/
veil...@redhat.com | libxml Gnome XML XSLT toolkit http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/
Sep 17-18 2001 Brussels Red Hat TechWorld http://www.redhat-techworld.com

John Fleck

unread,
Jul 15, 2001, 4:51:15 PM7/15/01
to
On Sun, Jul 15, 2001 at 02:50:34PM -0400, Daniel Veillard 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.
> >
> > Thoughts?
>
> Seems to me that you forget the very important point that most
> stylesheets are based on an existing core which is reused by all
> different styles (only part of the default formatting are overriden
> to provide a given style). Most of the XSLT code is Norm Walsh one and
> MUST be shared. Some extensions on top of it may be shared but will be
> relatively small in comparison.
>

Daniel's right, so all we need is a relatively modest customization
layer(s).

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?

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

Malcolm Tredinnick

unread,
Jul 15, 2001, 9:10:57 PM7/15/01
to
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!!

John Fleck

unread,
Jul 15, 2001, 11:00:17 PM7/15/01
to
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.

_______________________________________________

Daniel Veillard

unread,
Jul 16, 2001, 11:44:19 AM7/16/01
to
On Mon, Jul 16, 2001 at 10:11:05AM -0500, Dan Mueth wrote:
> I'm not worried about documents which don't specify a stylesheet. These

Just a quick note to point out that libxslt-1.0.0 has support
for the standard way to associate a stylesheet to an XML document,
namely the stylesheet PI mechanism:
http://www.w3.org/TR/xml-stylesheet/

The API is:
xsltStylesheetPtr xsltLoadStylesheetPI (xmlDocPtr doc);
http://xmlsoft.org/XSLT/html/libxslt-xsltinternals.html#XSLTLOADSTYLESHEETPI

and there is an example of use in xsltproc.c

Daniel

--
Daniel Veillard | Red Hat Network http://redhat.com/products/network/
veil...@redhat.com | libxml Gnome XML XSLT toolkit http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/
Sep 17-18 2001 Brussels Red Hat TechWorld http://www.redhat-techworld.com

_______________________________________________

David Merrill

unread,
Jul 16, 2001, 6:14:19 PM7/16/01
to
On Mon, Jul 16, 2001 at 10:10:43AM -0500, Dan Mueth wrote:
> I don't want to make things too complicated, but I don't expect that
> handling multiple stylesheets will be very hard. The hardest part will be
> keeping the stylesheet catalog. This should not be a big deal I don't
> think.

>
> I'm not worried about documents which don't specify a stylesheet. These
> documents are just displayed with the standard Norman Walsh stylesheet.
> Similarly, invalid stylesheet requests can just fall back to the default.
> Of course you shouldn't have invalid stylesheets if people put the
> appropriate dependency information into autoconf or the package info
> anyway. Most GNOME apps would depend on a GNOME stylesheet which is
> shipped with gnome-libs or gnome-core probably. Packages could also
> potentially ship a special stylesheet which is only used by the docs in
> that package if they want, although very few would actually do this.
>
> This should not make things any more complex for application developers
> and packagers unless they want to use a customized stylesheet. So, I
> don't see this as a burden on anybody except whoever writes and maintains
> this part of the help system. Also, nothing about this should be
> GNOME-specific. In fact, if we don't get the LDP and KDE to sign onto
> this, then there is no point in doing it.
>
> I don't want to push this too hard if others don't like the idea.
> However, I don't think it would be too hard to do, and I think a lot of
> groups (KDE, GNOME, LDP, Mozilla, various Linux/Unix/BSD distributors, and
> others) would take advantage of this feature and may more likely adopt a
> common help system* if it allowed them to still control the appearance of
> their documents.

Our stylesheet is very close to vanilla. If the ability to tailor a
stylesheet is available, we will probably take advantage of it, but
it's not a big issue, I don't think. I'll check with the list and make
sure, though.

> * I'm moving toward the idea of a free help system to be shared by these
> various groups/distributions. Among other things, it should be able to
> display any document so that it appears the way the author intended
> independent of the desktop or browser the user is using. It isn't clear
> how much of the code should be shared and how much should just follow a
> similar specification. I think we all have a lot to gain by working
> together to develop a common help system however.

There's something to be said for customization, but there's also
something to be said for consistency. I hate, for example, the fact
that LDP docs are in 6 different source formats that all render
differently. I'd hate to see Gnome present the same problem.

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

If one company dominates everything, it's dangerous. You kill innovation and
you lose the capacity to create alternatives. Ultimately, that isn't good
for the consumer or the country.
--Samuel Miller, U.S. Justice Department

John Fleck

unread,
Jul 16, 2001, 10:28:46 PM7/16/01
to
On Mon, Jul 16, 2001 at 11:41:26AM -0400, Daniel Veillard wrote:

> On Mon, Jul 16, 2001 at 10:11:05AM -0500, Dan Mueth wrote:
> > I'm not worried about documents which don't specify a stylesheet. These
>
> Just a quick note to point out that libxslt-1.0.0 has support
> for the standard way to associate a stylesheet to an XML document,
> namely the stylesheet PI mechanism:
> http://www.w3.org/TR/xml-stylesheet/
>

Thanks, Daniel.

So something like:

<?xml-stylesheet href="gnome-customization.xsl" type="text/xsl"?>

And how do I then resolve the actual location of "gnome-customization.xsl"?
Is there something analogous to catalog resolution I can use?

_______________________________________________

John Fleck

unread,
Jul 16, 2001, 10:33:42 PM7/16/01
to
On Mon, Jul 16, 2001 at 06:12:40PM -0400, David Merrill wrote:
>
> There's something to be said for customization, but there's also
> something to be said for consistency. I hate, for example, the fact
> that LDP docs are in 6 different source formats that all render
> differently. I'd hate to see Gnome present the same problem.
>

I agree here. I think what we're talking about is minor decorative
differences in order to create distinctions. Everything will be based
on Norman Walsh's stylesheets.

John Fleck

unread,
Jul 17, 2001, 12:46:40 AM7/17/01
to
On Tue, Jul 17, 2001 at 12:22:27AM -0300, Jorge Luiz Godoy Filho wrote:

> On Mon, 16 Jul 2001, jfl...@inkstain.net wrote:
>
> > <?xml-stylesheet href="gnome-customization.xsl" type="text/xsl"?>
> >
> > And how do I then resolve the actual location of
> > "gnome-customization.xsl"? Is there something analogous to catalog
> > resolution I can use?
>
> There's no catalog.
>
> This location is relative to your document. It can be pointed to any
> valid URI (file://, http://, /some/dir, etc.).
>

So what we want to do is install our stylesheets at
{prefix}/wherever/we/put/them

Where the user can pick prefix at install time.

And we for sure don't want to ship a stylesheet with each doc.

So how can we do this?

Daniel Veillard

unread,
Jul 17, 2001, 12:54:43 PM7/17/01
to
On Tue, Jul 17, 2001 at 12:22:27AM -0300, Jorge Luiz Godoy Filho wrote:
> On Mon, 16 Jul 2001, jfl...@inkstain.net wrote:
>
> > <?xml-stylesheet href="gnome-customization.xsl" type="text/xsl"?>
> >
> > And how do I then resolve the actual location of
> > "gnome-customization.xsl"? Is there something analogous to catalog
> > resolution I can use?
>
> There's no catalog.

Since the word 'catalog' doesn't even appears from the spec, I am wondering
how you can feel so positive about making such an assertion. This is
definitely not specified ! In the case of HTTP URI, caching is permitted
(since there is no way in this mechanism to disable caching), and at
that level a catalog implementing an HTTP cache mechanism sounds
perfectly adequate IMHO.

In the case of the libxml/libxslt implementation if a catalog is specified
this will go though the URI resolver processing and catalog checking
will occur.

> This location is relative to your document. It can be pointed to any
> valid URI (file://, http://, /some/dir, etc.).

More precisely this is an URI-Reference, with all the associated semantic
inherited from RFC2396.

So to answer John Fleck, yes catalogs will be taken into account by
libxslt when doing the resolution.

Daniel

--
Daniel Veillard | Red Hat Network http://redhat.com/products/network/
veil...@redhat.com | libxml Gnome XML XSLT toolkit http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/
Sep 17-18 2001 Brussels Red Hat TechWorld http://www.redhat-techworld.com

_______________________________________________

Daniel Veillard

unread,
Jul 17, 2001, 4:42:46 PM7/17/01
to
On Tue, Jul 17, 2001 at 04:19:00PM -0300, Jorge Luiz Godoy Filho wrote:
> On Tue, 17 Jul 2001, veil...@redhat.com wrote:
> I was talking about a catalog to reference stylesheets. That's what I
> understood from John's question.

yes and I see no problem for that. Even SGML catalogs allows
such caching as long as you're usung SYSTEM entries.

> I've never seen such a catalog for stylesheets but only for DTDs. From
> other parsers (mainly written in Java), I've seen some concern on
> making them able to read catalogs for DTDs, to ease

Well actually catalog are really only caches.
If you look at XML Catalogs, it's even more clear
http://www.oasis-open.org/committees/entity/

especially things like rewriteURI
http://www.oasis-open.org/committees/entity/spec-2001-07-16.html#s.rewriteuri

You can cache any entity you can name, and in the XML world everything
has an URI name, so everything is cacheable. This can be XSLT, CSS
stylesheets as well as text entities, etc ...

> And I still owe you some beer when you come to .br. :-)

Well I dind't planned such a trip yet :-)

Reply all
Reply to author
Forward
0 new messages