"Reece Dunn" <[EMAIL PROTECTED]> writes:
> Vladimir Prus wrote: >>David Abrahams wrote: >> > There's way too much detail in the TOC at the beginning of the >> > generated BoostBook docs, which makes it almost impossible to >> > navigate and very imposing to a newcomer. Can that be fixed? >> > If you let me know what kind of structure/design you are looking for, > I'll see if I can implement it. However it may be a week or so before > I can give you anything. It may also require overriding the DocBook > code which is something you want to keep to a minimum.
Well it seems to me that the TOC on the front page should list only the individual libraries and show no detail of their documentation structure.
Sure. This can be done by generating only part and chapter sections in the main ToC.
> Also, the lack of script support means that you can't implement a > collapsable heirarchy :(.
Actually I don't think scripting is completely out-of-the-question. See http://article.gmane.org/gmane.comp.lib.boost.devel/90591 for example. I think the main reason we decided to ban scripting in Boost web pages was that the chance of coming up with 20 different nonportable and variously-annoying applications of it is too high.
Okay.
If we could manage a single instance of the script code and if there was an alternative for browsers that don't support scripting, I think that would probably be OK.
If the script code is in a seperate file, the problem is where is this placed and how is it referenced? If the script code is inlined within the HTML, it can be managed at a single place in the BootBook code, something like:
<html><head>
<xsl:apply-templates name = "html.prelude"/>
</head>...</html> <xsl:template name = "html.prelude">
<script>...</script>
</xsl:template>An example is provided in toc-demo.html, but I don't know how portable it is. One issue with this approach is that it makes the chapter contents hidden on default (no good for browsers not supporting scripts). This means either (1) having the contents expanded by default; or (2) having a collapse-all function invoked when the document is loaded.
It might be worth trying for one release, to see how it goes over. It would also eliminate at least one excuse that certain library maintainers use for not improving their documentation ;->
It should be easy to make the BoostBook XSLT highly flexible in ToC generation, like I have done for the Boost banner/nav links (see tools/boostbook/xsl/navbar.xsl for the parameter descriptions). That way you can optionally tell it to use scripts, frames, both or neither.
> One possibility may be to support frames with the Boost banner in a > top pane, the top-level ToC contents in a left pane that links to an > expanded ToC for that chapter in the main pane. The navigation (prev, > next) will be in the content in the main pane at the top/bottom of the > document as is in the existing split HTML generation. The main content > will also have a home link that directs the browser window to the > frame content (<a target = "_top" href = "frames.html">home</a>). > > Are frames allowed in Boost documents? Thoughts? Alternate ideas?
Sure, frames are allowed, as are CSSes, which are more powerful than most people know.
I shall look into adding frame and collapsable ToCs in BoostBook later in the week and post the results.
I think you *can* implement a collapsible hierarchy with frames, just by automatically generating the right index pages. I don't think it's really helpful to have collapsibility at every level of hierarchy anyway. Those interfaces where everything collapses tend to be one of those "script annoyances" I was talking about earlier ;-)
The problem with this is that you would have N! ToC pages where N is the number of chapters (since you can have any combination collapsed/expanded). If you only allow one chapter to be expanded at any one time, this means having N toc pages which would be more feasible. I'll take a look at adding this to the possibilities generated.
Regards, Reece
_________________________________________________________________
Want to block unwanted pop-ups? Download the free MSN Toolbar now! http://toolbar.msn.co.uk/ Title: Collapsable ToC Demo
Part IChapter 1Chapter 2Part IIChapter 1
