Re: [boost] [Poll] New look-n-feel for Boost documentation

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