Boost logo

Boost :

From: Reece Dunn (msclrhd_at_[hidden])
Date: 2004-10-04 12:22:10

Jonathan Turkanis wrote:
> The really big problem is that the HTML for the index, which can be rather
> large, would be physically included in each content page. This could make the
> library documentation enormous.

The pages mentioned (e.g. use some form of server-side
processing like PHP scripts to add the ToC information on the fly. This
is not possible for off-line documents. There are, however, several
possible ways around this:

[1] Generate XHTML documents with an XSLT stylesheet to transform them
to HTML and handle an xi:include directive (within the stylesheet if the
XSLT engine does not support them). This would allow the ToC to be
maintained in a separate file, keeping doc bloat to a minimum.

This is not really a workable solution because of incompatibilities and
browser support isuues. Also, you will be transforming the document at
the client site each time they view a page, taking up resources on the
client machine.

[2] Supply the ToC as a separate HTML page and add it in via script.
Something like:

    <div class = "toc"><script>
       var toc = "toc.html" ); // [a]
       document.write( toc.document.body.innerHTML );

but I am not sure how to make [a] work generically and in the presence
of popup blockers.

[3] Provide a toc.xml file that the JavaScript class will process to
generate the tree navigation, e.g.

    <script>var toc = new toc_tree();</script>
    <div class = "toc"><script>toc.loadXML( "toc.xml" );</script></div>

This will reduce doc bloat, but I am not sure how you can process the
XML file generically.

SUMMING UP: IMHO, frames are the best option. For those that don't want
to view the docs in frames should be able to and a master ToC should be
kept, even if there is a ToC in the side frame (that is, the ToC like we
have at the moment should be retained, allowing easier navigation when
not viewing the docs within frames).

The BoostBook generated files produce a master ToC and add a navigation
link to it. It should be possible to add a link to select/deselect frames.


Boost list run by bdawes at, gregod at, cpdaniel at, john at