Re: Yelp document chunking

[Shaun McCance <shaunm wolfram com>]

As promised, I've finished a set of stylesheet changes to implement a
different chunking behavior.  I've filed a bug for this and attached my
stylesheet changes there.

http://bugzilla.gnome.org/show_bug.cgi?id=114117

This is pretty much a complete overhaul of Yelp's customizations.  The
new stylesheet is much better about chunking/displaying lots of types of
nodes that the old stylesheet was just clueless on.  Introductory text
(like, say, in an abstract) now actually gets displayed somewhere. 
Everything is just generally far better supported.

With the old stylesheets, if a sect2 was chunked, its content was also
displayed in its parent sect1.  I found this rather annoything.  These
new stylesheets do not do that.  Instead, the sect1 will have whatever
introductory text it contains, and then links to the sect2 chunks it
contains.

That said, it does have problems.  The Galeon manual doesn't work, but
it didn't work with the old stylesheets either.  This is because it
isn't valid DocBook.  (Hey, Galeon developers, article can't contain
chapter.  Make it a book.)  The Glade Turbo-Start doesn't work, and I'm
not sure why.  The Glade FAQ doesn't work, and I know exactly why, and
I'll fix it soon.  When I fix it, it will work better than it did with
the old stylesheets.

As promised, I checked AisleRiot with my new stylesheets.  I'm afraid
it's not perfect.  While the preface and glossary get chunked, when you
click them, Yelp won't load them.  Other than that, it works fine.  I
will figure out how to fix the preface/glossary issue.  For those not
aware, AisleRiot's manual doesn't work at all with the old stylesheets,
so my stylesheets are an improvement.  Oh, and the 'Next' link into the
glossary says 'Next'.  It ought to say 'Glossary'.  That should be an
easy addition, provided 'Glossary' is in the translation table.

The only other issue is the sidebar.  The sidebar doesn't get its nodes
the same way, so there isn't a one-to-one correspondance between the
nodes in the sidebar and the things that are chunked.  As Mikael pointed
out, this isn't necessarily a problem, as the sidebar could just jump
into the relevant fragment of a chunk.  That, however, assumes that Yelp
is actually capable of scrolling to anchors, which it isn't.

I basically looked through all the documentation installed on my system.
These were the only problems I encountered.  I would really like to get
this in for 2.3.3.  This constitutes a fairly major feature, so really
shouldn't go in after June 9.  So if it's not in 2.3.3, then it's not in
2.4.  It has a lot of advantages, and only presents a regression with
the Glade manauls.  And I can fix those before 2.4.  Getting this into
the 2.3 series would really help to iron out any issues I've missed.

--
Shaun