From: Doug Gregor (dgregor_at_[hidden])
Date: 2004-09-30 09:11:50
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