Re: [boost] Re: JavaScript index?

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. www.lyx.org) 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 = window.open( "toc.html" ); // [a]
       document.write( toc.document.body.innerHTML );
       toc.close();
    </script></div>

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.

Regards,
Reece