From: Doug Gregor <dgregor@cs.indiana.edu>
On Sep 30, 2004, at 8:51 AM, Rob Stewart wrote:
4. Some things don't adapt well to differing resolutions and font sizes. Consider the preferred/portable syntax table at
http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ function.tutorial.html#id478061. At my default settings, I see half of the second column. Were the table not offset so far, I'd see the whole thing. However, it is clear that things are set to not wrap (non-breaking spaces, perhaps?), so the side-by-side presentation means the table is likely to be wide and trigger scrolling. The second preferred/portable syntax entry in that section recognizes the problem and uses two tables, one above the other. Were it not for the extra large offset, the "Preferred syntax" table would fit at my default settings. The point is that while you cannot control a reader's resolution or font choices, and scrolling is inevitable, reducing the offset and avoiding wide, non-wrapping layouts is superior.
Those tables themselves are absolutely horrible, and should be replaced with something less restrictive. Unfortunately, I don't have a better way to present equivalent alternative code snippets.
Wouldn't this be just as useful? <H3>Preferred Syntax</H3> <code>boost::function<float (int x, int y)> f;</code> <H3>Portable Syntax</H3> <code>boost::function2<float, int, int> f;</code>
5. In
http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ function.tutorial.html#id478410, a list is introduced with, "Three such libraries are summarized below:," but there are no bullets setting off the three paragraphs. Is this a Boost.Function documentation issue or is this a consequence of the new style? If the latter, there should be bullets to clearly delineate each item.
I see bullets in Safari (?)
I couldn't reproduce it using just the HTML that appears there. That led me to the CSS. There I found: ul { list-style-image: url(images/bullet.gif); text-align: justify; } I then tried looking at http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/images/bullet.gif and got a 404.
8. When looking at
http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ ref.reference.html#header.boost.ref.hpp, there's no indication that there is documentation on boost::reference_wrapper. The link mentioned in 6 got me to the documentation page, but when I went up to http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ref..html, and then to http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ref.reference.html, I was unsure how to get back to
http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ ref.reference.html#header.boost.ref.hpp, since the link was in the "Header" section. Is this a consequence of the documentation or the new style? I'd prefer to see something like this in the "Reference" section or a "Description" section:
reference_wrapper - <brief> ref - <brief> cref - <brief> is_reference_wrapper - <brief> unwrap_reference - <brief>
where the names are the same links as in the Header section.
BoostBook has always been this way; the new look-n-feel does not change that. Would these links be in addition to the prototypes already provided?
Yes. As shown above, they are presented as documentation links. As currently presented by BoostBook, I'd expect the links to take me to code. They are, after all, in the "Header" section. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;