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

From: Rob Stewart (stewart_at_[hidden])
Date: 2004-09-30 11:51:34

From: Doug Gregor <dgregor_at_[hidden]>
> 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_at_[hidden]
Software Engineer                     http://www.sig.com
Susquehanna International Group, LLP  using std::disclaimer;