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