We have a kind of policy against using scripting in our library doc pages, mostly because in the past scripts have caused major portability or usability problems. I personally love the menu on the left of the serialization lib docs page, but if it uses scripts and we can't really be assured that they'll work everywhere, it probably ought to be removed. There are alternatives that might actually be more usable: http://article.gmane.org/gmane.comp.lib.boost.documentation/389 -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
"David Abrahams" <dave@boost-consulting.com> wrote in message news:upt6yfu2y.fsf@boost-consulting.com...
We have a kind of policy against using scripting in our library doc pages, mostly because in the past scripts have caused major portability or usability problems. I personally love the menu on
the
left of the serialization lib docs page, but if it uses scripts and we can't really be assured that they'll work everywhere, it probably ought to be removed.
I think Robert's menu is very effective, and was hoping it represented a de facto relaxation of the no-script policy. I think script problems can be resolved by (i) Having a (small) boost-wide library of javascipt components which have been tested on a large number of browsers and which all library authors would have to use. To begin with, it could just contain a tree control like Robert's; maybe that would be enough. (ii) Requiring all documentation to support a no-script option. In a former life I did a lot of javascript programming. I'd volunteer to write the first component and test it on a large number of broswers on windows and linux. Jonathan
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
"David Abrahams" <dave@boost-consulting.com> wrote in message news:upt6yfu2y.fsf@boost-consulting.com...
We have a kind of policy against using scripting in our library doc pages, mostly because in the past scripts have caused major portability or usability problems. I personally love the menu on
the
left of the serialization lib docs page, but if it uses scripts and we can't really be assured that they'll work everywhere, it probably ought to be removed.
I think Robert's menu is very effective, and was hoping it represented a de facto relaxation of the no-script policy.
I think script problems can be resolved by
(i) Having a (small) boost-wide library of javascipt components which have been tested on a large number of browsers and which all library authors would have to use. To begin with, it could just contain a tree control like Robert's; maybe that would be enough.
(ii) Requiring all documentation to support a no-script option.
In a former life I did a lot of javascript programming. I'd volunteer to write the first component and test it on a large number of broswers on windows and linux.
I accept. Others can howl at will. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
On Wed, 14 Jul 2004 13:58:26 -0600, Jonathan Turkanis <technews@kangaroologic.com> wrote:
I think script problems can be resolved by
(i) Having a (small) boost-wide library of javascipt components which have been tested on a large number of browsers and which all library authors would have to use. To begin with, it could just contain a tree control like Robert's; maybe that would be enough.
(ii) Requiring all documentation to support a no-script option.
In think (ii) is an absolute requirement. I find myself using text-based browsers from time to time, especially when working across an SSH connection, and I get quite annoyed by some documentation sites that navigation exclusively though Javascript. I would hate for boost to go the same way. In addition to some text browsers not supporting Javascript at all, the CERT has on numerous occasions advised that Javascript be disabled in browsers such as IE for security reasons, and some companies make that a policy decision. /Mattias
Jonathan Turkanis wrote:
I think Robert's menu is very effective, and was hoping it represented a de facto relaxation of the no-script policy.
I have some reservation 1. It does not work very nice when image loading is turned off (as it is for me). 2. It takes qutie a lot of screen space.
I think script problems can be resolved by
(i) Having a (small) boost-wide library of javascipt components which have been tested on a large number of browsers and which all library authors would have to use. To begin with, it could just contain a tree control like Robert's; maybe that would be enough.
I think it's probably better to somehow make all new libraries use Boost.Book. If that's done, any presentation issues can be solved in one place. For example, I think there were already discussion about expandable TOC on the boost-doc failings list. At all events, I'd prefer constistent look of all Boost library docs (and the ability to print them), to every author introducing something they like. - Volodya
"Vladimir Prus" <ghost@cs.msu.su> wrote in message news:200407151037.40144.ghost@cs.msu.su...
Jonathan Turkanis wrote:
I think Robert's menu is very effective, and was hoping it represented a de facto relaxation of the no-script policy.
I have some reservation
1. It does not work very nice when image loading is turned off (as it is for me).
Good point -- I hadn't thought of that. It's possible -- using tiny HTML tables -- to generate the icons without using any image files :-P ... but I'd like to know how many people turn image loading off.
2. It takes qutie a lot of screen space.
I guess this is a matter of taste. Some existing libraries have a navigation panel on the left (maybe PP is the only one), so this issue isn't really related to scripting.
I think script problems can be resolved by
(i) Having a (small) boost-wide library of javascipt components
have been tested on a large number of browsers and which all
authors would have to use. To begin with, it could just contain a
which library tree
control like Robert's; maybe that would be enough.
I think it's probably better to somehow make all new libraries use Boost.Book. If that's done, any presentation issues can be solved in one place. For example, I think there were already discussion about expandable TOC on the boost-doc failings list.
At all events, I'd prefer constistent look of all Boost library docs (and the ability to print them), to every author introducing something they
This may be a good solution. But I think there would still be a need for a javascript component for use by Boost.Book. From my point of view -- if I'm writing the script -- it makes no difference whether it's to be used by individual library authors or by Boost.Book. like. I agree completely.
- Volodya
Jonathan
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
"Vladimir Prus" <ghost@cs.msu.su> wrote in message news:200407151037.40144.ghost@cs.msu.su...
Jonathan Turkanis wrote:
I think Robert's menu is very effective, and was hoping it represented a de facto relaxation of the no-script policy.
I have some reservation
1. It does not work very nice when image loading is turned off (as it is for me).
Good point -- I hadn't thought of that. It's possible -- using tiny HTML tables -- to generate the icons without using any image files :-P ... but I'd like to know how many people turn image loading off.
2. It takes qutie a lot of screen space.
I guess this is a matter of taste. Some existing libraries have a navigation panel on the left (maybe PP is the only one), so this issue isn't really related to scripting.
No, but frames present a different problem: it can be hard to link to individual pages in the doc. Ultimately the ideal thing would be that the browser "thinks" it's visiting an address that causes the index and content pages to come up exactly as they're being viewed, but I've never seen a frames-based interface that works that way. The best thing I can suggest is that we include a "link to this page" link on each page of documentation.
I think it's probably better to somehow make all new libraries use Boost.Book. If that's done, any presentation issues can be solved in one place. For example, I think there were already discussion about expandable TOC on the boost-doc failings list.
This may be a good solution. But I think there would still be a need for a javascript component for use by Boost.Book. From my point of view -- if I'm writing the script -- it makes no difference whether it's to be used by individual library authors or by Boost.Book.
Yes.
At all events, I'd prefer constistent look of all Boost library docs (and the ability to print them), to every author introducing something they like.
I agree completely.
But can we agree on a look/feel that works? Several library authors seem convinced that the "usual conventions" are broken and won't be satisfied unless they can stamp their own notions of usability on their docs. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
"David Abrahams" <dave@boost-consulting.com> wrote in message news:ubrih5tb5.fsf@boost-consulting.com...
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
"Vladimir Prus" <ghost@cs.msu.su> wrote in message news:200407151037.40144.ghost@cs.msu.su...
Jonathan Turkanis wrote:
I think Robert's menu is very effective, and was hoping it
<snip>
2. It takes qutie a lot of screen space.
I guess this is a matter of taste. Some existing libraries have a navigation panel on the left (maybe PP is the only one), so this issue isn't really related to scripting.
No, but frames present a different problem: it can be hard to link to individual pages in the doc.
Ultimately the ideal thing would be that the browser "thinks" it's visiting an address that causes the index and content pages to come up exactly as they're being viewed, but I've never seen a frames-based interface that works that way.
Could you explain what you mean by 'come up exactly as they're being viewed'? I think I understand, but I'm not sure. It's possible to have a library's homepage parse the portion of its url following '?' and load a particular page into the index frame and another into the content frame. This would allow, e.g., links into the reference documentation of Boost.PP. I'm not sure this is what you're talking about, though.
At all events, I'd prefer constistent look of all Boost library docs (and the ability to print them), to every author introducing something they like.
I agree completely.
But can we agree on a look/feel that works? Several library authors seem convinced that the "usual conventions" are broken and won't be satisfied unless they can stamp their own notions of usability on their docs.
Maybe not. But at least some of the current variation seems unrelated to usability (for instance, the font size for preformatted text.) Maybe a more comprehensive boost.css and some more templates would help. Jonathan
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
"David Abrahams" <dave@boost-consulting.com> wrote in message news:ubrih5tb5.fsf@boost-consulting.com...
I guess this is a matter of taste. Some existing libraries have a navigation panel on the left (maybe PP is the only one), so this issue isn't really related to scripting.
No, but frames present a different problem: it can be hard to link to individual pages in the doc.
Ultimately the ideal thing would be that the browser "thinks" it's visiting an address that causes the index and content pages to come up exactly as they're being viewed, but I've never seen a frames-based interface that works that way.
Could you explain what you mean by 'come up exactly as they're being viewed'? I think I understand, but I'm not sure.
I mean, you're looking at the documentation, so you copy what's in your browser's "address" field and paste it into an email message. The recipient of the email visits that URL and sees exactly what you're seeing (modulo scrollbar position, formatting differences, etc.)
It's possible to have a library's homepage parse the portion of its url following '?' and load a particular page into the index frame and another into the content frame. This would allow, e.g., links into the reference documentation of Boost.PP. I'm not sure this is what you're talking about, though.
I think it is, as long as when we move between content pages in the documentation the address field in the browser can be appropriately updated.
At all events, I'd prefer constistent look of all Boost library docs (and the ability to print them), to every author introducing something they like.
I agree completely.
But can we agree on a look/feel that works? Several library authors seem convinced that the "usual conventions" are broken and won't be satisfied unless they can stamp their own notions of usability on their docs.
Maybe not. But at least some of the current variation seems unrelated to usability (for instance, the font size for preformatted text.) Maybe a more comprehensive boost.css and some more templates would help.
I hope so. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
"Jonathan Turkanis" wrote:
Good point -- I hadn't thought of that. It's possible -- using tiny HTML tables -- to generate the icons without using any image files :-P ... but I'd like to know how many people turn image loading off.
Me too. I guess there are more with dialup. /Pavel
"Jonathan Turkanis" <technews@kangaroologic.com> wrote in message news:...
(i) Having a (small) boost-wide library of javascipt components which have been tested on a large number of browsers and which all library authors would have to use.
I case I wasn't clear ... I mean 'all library authors who wish to use scripts'. Jonathan
David Abrahams wrote:
We have a kind of policy against using scripting in our library doc pages, mostly because in the past scripts have caused major portability or usability problems. I personally love the menu on the left of the serialization lib docs page, but if it uses scripts and we can't really be assured that they'll work everywhere, it probably ought to be removed.
There are alternatives that might actually be more usable: http://article.gmane.org/gmane.comp.lib.boost.documentation/389
I really liked Robert's Javascript tree control for the serialization library docs. To support your case, however, I noticed that IE 6 would not show the dot.gif image but would show the plus.gif image. On Mozilla everything is shown properly.
Edward Diener wrote:
David Abrahams wrote:
We have a kind of policy against using scripting in our library doc pages, mostly because in the past scripts have caused major portability or usability problems. I personally love the menu on the left of the serialization lib docs page, but if it uses scripts and we can't really be assured that they'll work everywhere, it probably ought to be removed.
There are alternatives that might actually be more usable: http://article.gmane.org/gmane.comp.lib.boost.documentation/389
I really liked Robert's Javascript tree control for the serialization library docs. To support your case, however, I noticed that IE 6 would not show the dot.gif image but would show the plus.gif image. On Mozilla everything is shown properly.
This is corrected for me in the latest CVS download.
participants (6)
-
David Abrahams -
Edward Diener -
Jonathan Turkanis -
Mattias Flodin -
Pavel Vozenilek -
Vladimir Prus