"Reece Dunn" <msclrhd@hotmail.com> wrote in message news:BAY7-F13WJ56Asu6JQK0003fc9c@hotmail.com...

Jonathan Turkanis wrote:

...

I've thought a bit more about this, and it occured to me that if the tree is displayed in the same frame as the content, it's state will not be preserved when a link is followed unless this info is added to the url. So it appears this idea suffers from the same problems as Reece's suggestion.

The question here is: are we going to place the emphasis on auto-generated docs?

Let's do both :-)

If we do this, then it should be possible to do something like:

<span onclick = "follow_link(1.5)">Chapter 1.5</span>

This would be embedded in an anchor element, to allow links to work on no-script browsers? I think this should work.

With regards to the page refreshing, this happens when you select "sync" anyway.

Yes, but I was thinking that "sync" would be used relatively infrequently, whereas following links within a page is common.

Is it possible to use '#' instead of '?', so the browsers won't refresh the docs.

If we use Rene's idea of displaying the tree in the content frame, then yes (I think). Otherwise, the url with the correct fragement identifier won't be displayed in the address bar. Including the tree in the content frame is a big problem, though. When I replied to Rene I was mostly worried about download times when viewing the docs online. But if a large part of the docs eventually use trees, it could unnecessarily increase the size of the Boost distribution. We could use iframes, but this won't work for old browsers.

This might require a standard naming scheme for <a name = "..."/> marked sections, but this would be easier to do if the docs are auto-generated.

For older docs that want to keep their HTML structure but move over to the treeview control, it should be easy to do if: 1. They are compatible with XHTML (i.e. they can be loaded in an XML client and manipulated via an XSLT stylesheet, e.g. using xsltproc). NOTE: This should be trivial if the HTML has been run through htmltidy. 2. The section format follows a regular pattern, e.g. h1 elements for level 1, h2 for level 2, etc.

This would allow you to: 1. Insert and generate the treeview control by making a pass over

Yeah. the hN

tags. 2. Clean up sections of the form: <a name = "..."/><hN>...</hN>

I thought about writing a perl script which would scan a library's doc directory and try to build a menu page. But when I saw the wide variation in existing documentation, I was not optimistic. The issus would be the same with XSLT, I think.

Issues would be: 1. Do we remove the ToC provided in the HTML doc (can we detect and remove/use it?) 2. Have we detected the document structure correctly? 3. Other issues I've missed.

It sounds pretty messy. I think a lot will have to be done by hand. :-( I'd like to focus on: 1. Providing a tree control which library authors can add to hand-written docs 2. Allowing docs generated with Boost.Book to have a built-in tree control, with automatic synchronization if possible 1) is basically done, unless someone has an idea how to eliminate the need for [sync] 2) is doable, with hitch that linking within a page causes a reload (unless I misunderstood your suggestion) I think only time will tell whether it's more annoying to have to manually [sync] the documentation or to reload the docs when linking within a page. So I'd say two variants of 2) should be pursued: one which produces docs using the existing tree component, and one which produces auto-syncing docs. Jonathan