Yelp document chunking

[Shaun McCance <shaunm wolfram com>]

I really don't like Yelp's current method of chunking documents.  To
explain why, let's consider a document with the following structure:

Section 1
Section 2
   Section 2.1
   Section 2.2
Section 3
   Section 3.1

Currently, Yelp provides a complete document for each of the above
nodes.  The document created for Section 2, however, contains all the
text of both Section 2.1 and Section 2.2.  This leads to quite a few
problems:

*  It's conceptually difficult, since there isn't a one-to-one
correspondance.

*  Previous and Next links are difficult to understand.  Currently, they
link to the previous or next thing at that level, regardless of whether
or not it is a sibling.  So the Next link of Section 2.1 points to
Section 2.2, and the Next link of Section 2.2 points to Section 3.1. 
The Next link of Section 2 points to Section 3.  Presumably, this is
done so that you have a choice of how you want to read the document. 
The problem is that, if Section 2 contains introductory text, you'll
never see it if you're browsing along at the sect2 level.

*  Internal links are just totally borked.  If I'm reading something
that has a link to something in Section 2.1, should that link go to the
Section 2.1 document, or the Section 2.1 location in the Section 2
document.  Currently, it goes to Section 2.1.  But if you're browing
along at the sect1 level, this is almost certainly not what you want.

*  Introductory text rarely works as you expect, and sometimes doesn't
work at all.  The current chunking behavior makes bug #98361 pretty much
impossible to solve well.


I'm working on a set of changes to the stylesheets to change this
behavior.  However, I'd like to get input on exactly why Yelp chunks the
way it does.  The only reason I can see is that it allows you to choose
the level of granularity to browse at.  I don't see that as a good
enough reason to introduce all these problems, though.

What I would prefer is that we just make a choice of which types of
nodes get chunked (chapter, sect1, sect2, etc.) and do things that way. 
If a sect 1 contains sect2's, then the sect1 document will have whatever
introductory text it contains, and then links for its subsection.  This
is the approach taken for the GNOME User's Guide (multiple-page version)
on www.gnome.org/learn.

Simplifying the chunking mechanism and navigational model will allow us
to make a lot of internal linking stuff work more cleanly, and will make
it easier to rethink part of the interface (as per, for example, much of
the discussion on bug #91610).

--
Shaun