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.
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 (?)
6. At the bottom of that same page, links to boost::ref refer to here:
http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ reference_wrapper.html#id444666, which says nothing about "boost::ref." References to that name appear earlier in the linked document. Again, I don't know whether this is an issue with the Boost.Function documentation or the new style, but it will be a source of confusion.
It's the documentation for "ref", which is grouped with reference_wrapper. If there is a problem here, it's not with the stylesheet.
7. The links to the documentation should probably be encoded by the author similarly to those in the C++ Standard. That is, instead of id444666, the link name could be "ref.desc.ctor" or something.
We're working on that.
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? Doug