[boost] Re: Re: Re: Javascript Tree Control [was: Serialization Menu]

From: Jonathan Turkanis (technews_at_[hidden])
Date: 2004-07-31 12:58:24

"Reece Dunn" <msclrhd_at_[hidden]> wrote in message
news:BAY7-F13WJ56Asu6JQK0003fc9c_at_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.

Yeah.

> 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
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