Re: Plan for the YelpDocument branch

[Shaun McCance <shaunm gnome org>]

On Thu, 2007-04-05 at 21:06 +0100, Don Scorgie wrote:
> > I had envisioned the following document types:
> >   YelpDocbook: a single DocBook document
> >   YelpInfo:    a single info document
> >   YelpInfoToc: the TOC listings for info pages
> >   YelpMallard: a single Mallard document
> >   YelpMan:     a single man page
> >   YelpManToc:  the TOC listings for man pages
> >   YelpSearch:  a singleton document managing all searches
> >   YelpToc:     the main TOC listings
> > 
> > Clearly, the three bits that deal with TOCs needs to be
> > coordinated with Don's Spoon work.  But the rest of them
> > should be largely independent of that work.
> 
> The Spoon stuff should remove virtually all the parsing code in the
> TOCs, so each YelpDocument should only require a couple of simple calls
> (see the yelp-spoon branch yelp-toc-pager.c for how simplified the main
> TOC stuff becomes ;) ).

I'd intended to have the multiple TOC documents specifically
because yelp-toc-pager has too much unrelated code inside it
right now.  But if Spoon makes the file trivial, then we can
probably just keep a single TOC document.

> How is the section-tree view handled in the New World Order?

At the moment, the thought is to have this:

GtkTreeModel* yelp_document_get_sections (YelpDocument *document);

I had toyed with the idea of making a YelpDocument just *be* a
GtkTreeModel, but that might be more trouble than it's worth.
What I'd like to address is the shifting sidebar problem.  The
way it appears and disappears on different documents is really
annoying.

What I'm thinking is that, for different types of documents,
there are other things that could possibly go into a sidebar.
In Mallard, for instance, a section heirarchy doesn't make
any sense.  But we could display "see also" links and such
in a sidebar.

>   Also, (I
> know you've probably not thought about this, but) how would document
> printing happen?  Right now, it's special-cased and drawn to an
> off-screen html widget, which is kind-of hacky [1].

I would love nothing more than to have a complete toolchain
for creating PS/PDF from our document sources.  Then we could
integrate that into Yelp, and YelpWindow could just make page
requests for the printable content.  That would rule.

But that toolchain has proven to be very elusive.

>   Would it be
> possible in this scheme to make a request for the entire document to be
> handled and passed back as one huge chunk of html?  This would simplify
> things once more (and hopefully also allow info document printing).

We could just make a fake page ID (like we do for the title
page, for instance) which means "entire document".  So you
could just do something like:

yelp_document_get_page (document, "-x-yelp-wholepage");

Since page loads are on-demand (or the API at least allows
them to be), the document only needs to do this when it's
requested.  This is a big advantage over the pager API.

--
Shaun