On Wed, 29 Sep 2004 18:55:01 -0400, David Abrahams wrote

That is a beautiful piece of work. I don't know what the next step is, but maybe it would be a good idea to take an informal poll. Does anyone actually object to the idea of integrating this thing into the official Boost documentation?

I agree, it is well done -- I think we should go for it -- presumably meaning integrate it with boost-book. We can't really do much with 'all html' docs, right? Jeff

"Reid Sweatman" <drunkardswalk@earthlink.net> wrote in:

...

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of David Abrahams Sent: Wednesday, September 29, 2004 4:55 PM To: boost@lists.boost.org Cc: boost-docs@lists.sourceforge.net Subject: [boost] Re: JavaScript index?

<snipped>

...

That is a beautiful piece of work. I don't know what the next step is, but maybe it would be a good idea to take an informal poll. Does anyone actually object to the idea of integrating this thing into the official Boost documentation?

I believe I was actually responding to this post with my post to the "new look and feel" thread. Apologies. Yes, beautiful, and very nicely done. But have a look at what I said there, and see if there was any merit in my comments (and should they prove content-free, I'll re-lurk, or to put it more poetically, "steal softly and silently away." <g>).

I don't see a post by you which appears to be intended for this thread ... Wait -- is this it?

I agree, especially with the remark concerning a single-page option; why not turn that into a "print version" if possible? The two things I note are that the numbering is left-justified, which isn't the norm for a TOC, and that the items B, C, and D at the bottom of the first page don't correlate syntactically with anything else on the page in an obvious manner, and beg the obvious question concerning A.

If so, could you explain what you mean about the numbering being left-justified? Also, I know that I use A, B, C, D as section labels in the example website (http://tinyurl.com/5wbcw) but otherwise I don't follow you. I apologize if this is not the passage you were referring to. Your comments about accessibility in the other thread are important, too. With the tree control, I went out of my way to make sure pages could be bookmarked and that the documentation was viewable with text-only browsers. Are there other accessibility problems you see? Best Regards, Jonathan

"Reid Sweatman" <drunkardswalk@earthlink.net> wrote in message:

Sorry, but I've lost the message that had the link I looked at. I did look at the link above, and apart from possible reservations regarding frames, had no problem with the look and layout. The other link was to a more complex page that used the JavaScript tree generator; the tree involved had the problems I mentioned, at least on IE 6.newest.

The trouble is I don't know what page you are talking about, and I didn't understand the problems you were trying to describe. When you find the link, please let me know.

Reid

Jonathan

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of David Abrahams Sent: Thursday, September 30, 2004 6:04 AM To: boost@lists.boost.org Subject: [boost] Re: JavaScript index?

"Reid Sweatman" <drunkardswalk@earthlink.net> writes:

...

...

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of David Abrahams Sent: Wednesday, September 29, 2004 4:55 PM To: boost@lists.boost.org Cc: boost-docs@lists.sourceforge.net Subject: [boost] Re: JavaScript index?

<snipped>

...

That is a beautiful piece of work. I don't know what the next step is, but maybe it would be a good idea to take an informal poll. Does anyone actually object to the idea of integrating this thing into the official Boost documentation?

I believe I was actually responding to this post with my post to the "new look and feel" thread.

Link, please?

Sorry. I forget that just because it's two inches away in my news reader doesn't mean you have an obvious link to it. From the archive: http://article.gmane.org/gmane.comp.lib.boost.devel/111009 Reid

"Daryle Walker" <darylew@hotmail.com> wrote in message:

...

That is a beautiful piece of work. I don't know what the next step is, but maybe it would be a good idea to take an informal poll. Does anyone actually object to the idea of integrating this thing into the official Boost documentation?

Yes, I object. I prefer not to have frames. The lettering Jonathan used was too small for my tastes. The lettering size can be fixed, but both the frames had horizontal scroll bars for some of his combinations of HTML code (even with the tiny text). That demonstrated the potential rendering nightmares frames can cause.

It's possible to hide the scrollbars, and require users to resize the frames when an index entry is not completely visible.

I've seen some web pages that use CSS to define two "frames" seamlessly, but in the same file. See the <http://synopsis.fresco.org> page mentioned in another thread. That looks cooler, and it degrades better when printing (or for accessibility).

This depends on setting the navigation pane's CSS position propty to 'fixed', which is not supported by some old browsers. One of the main design goals was that it could be viewed with almost any browser. Two other problems: 1. It violates the 'non-intrusive' requirement for docs that are being written by hand, since the HTML for the index gets mixed together with the actual content. For automatically generated docs this is not a problem. 2. It can lead to doc bloat, since the index will be physically included in every page. This is a show-stopper, IMO. The look you like can be acheived using geneuine HTML frames or iframes by setting their stylistic properties appropriately. The problem is that when the table of contents for a large library is expanded, the bottom part will be cut off. Notice that the navigation panel on the pages you mentioned are relatively small. For contrast, see http://tinyurl.com/4qjh6. If i suppressed the scrollbars (which I could) you wouldn't be able to view the entire table of contents.

Could those seamless content tables still use JavaScript?

Yes.

-- Daryle Walker Mac, Internet, and Video Game Junkie darylew AT hotmail DOT com

_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

Daryle Walker wrote:

I've seen some web pages that use CSS to define two "frames" seamlessly, but in the same file. See the <http://synopsis.fresco.org> page mentioned in another thread. That looks cooler, and it degrades better when printing (or for accessibility). You can also have the two columns next to each other without the "frame" effect, _and_ without a huge "table" layout. See the various pages at <http://www.mozilla.org> for that effect, including mastheads.

Jonathan, I don't know if this is any use, but the www.lyx.org pages do not use frames at all, yet have a menu that is fixed when the page is scrolled. The effect is similar to the one you achieve using frames. Regards, Angus

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

"Paul Mensonides" <pmenso57@comcast.net> writes:

...

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Reece Dunn

...

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

The documentation can be built during the build process on a client machine--which can be parametized by the particular user's preferences--i.e. there can be more than one available XSLT transformation. There are always going to be people that prefer fancy versions and people that prefer baseline versions, and there is no way to please everybody at once without having multiple ways to view the same docs.

If you count PDF, we already have multiple ways. There's no way to please _everybody_, period. I think we need to make some judgement about what's a reasonable level of accomodation and just stop there. I'm not sure if you were suggesting this, but IMHO asking users to run a build process just to look at the documentation would be a mistake. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com

"Paul Mensonides" <pmenso57@comcast.net> writes:

I'm not suggesting that it be the *only* way. What I'm suggesting is that we have a midpoint transformation that isn't too fancy and PDF's for the website and the distribution, but also provide the XML sources, a baseline XSLT transformation source, a semi-fancy XSLT transformation source, and the tools (i.e. scripts) to produce builds. Over time, more transformations can be added (if desired) for various purposes (such as generating plaintext, man pages, or whatever). Thus, there is no requirement on users, but the system is flexible and open-ended and minimizes the impact of choices such as frames vs. no-frames, script-based table of contents vs. not, underlined vs. non-underlined links, color-coded source snippets vs. not, blue headings vs. black headings, etc., etc..

Sounds workable (to someone with my limited knowledge). -- Dave Abrahams Boost Consulting http://www.boost-consulting.com

Jonathan Turkanis wrote:

...

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:

I'm not sure of the relevance of the server side scripts. Do you mean that they have the freedom to tailor content to browser capabilities,

Yes. (Although the pages are off line tonight. Machine maintenance.)

or that they avoid doc-bloat by keeping just one copy of the table of contents?

No, the html is generated dynamically, adding header and footer code to the main content that is stored in the .php file. The header includes the generated toc.

Either way, since boost docs have to be viewable offline, the only workable solution is frames, as I think you agree.

Fair enough. Angus

On Sun, 3 Oct 2004 13:46:22 -0600, Jonathan Turkanis <technews@kangaroologic.com> 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

"Caleb Epstein" <caleb.epstein@gmail.com> wrote in message news:989aceac041004104824d6f905@mail.gmail.com... the

...

library documentation enormous.

What about a middle ground? The index can live in its own frame to prevent this duplication of code, but there could be some level of navigation available on each page (e.g. prev/next/up/down links). This way folks who dislike or can't view frames can still find their way around.

This is what I favor for automatically generated documentation. It doesn't work for handwritten docs, since adding the prev/next/up/down is 'tedious and error prone'. Jonathan