Boost logo

Boost :

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

From: "Eric Niebler" <eric_at_[hidden]>
> Joel de Guzman and I, with the help of many smart folks on the
> boost-docs list[*], have been working on improving the look-n-feel of
> Boost's documentation. We're ready to commit the new style, but wanted
> to check here first.

Thanks to all those involved. Generally, the new style is clean,
professional, and attractive. I do have a few complaints,

1. My browser's "always underline links" setting is not being
   respected. I prefer links to be underlined so they are more
   visible. Color alone is not an indication. In case it
   matters, by user agent string is:

   Mozilla/5.0 (X11; U; SunOS sun4u; en-US; rv:1.0.1) Gecko/20020920 Netscape/7.0

2. My browser's link colors are not being honored. Thus, the
   link color isn't my normal link color and they don't change to
   indicate when I've visited them.

3. Sans serif text is harder to read. You should use a font with
   serifs for the body text and sans serif fonts for headings.

4. Some things don't adapt well to differing resolutions and font
   sizes. Consider the preferred/portable syntax table at
   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

5. In,
   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

6. At the bottom of that same page, links to boost::ref refer to
   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

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

8. When looking at,
   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, and
   then to,
   I was unsure how to get back to,
   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.

9. Headings and links should not share the same color, whatever
   choice you make for them. Blue is the traditional link color,
   but, as I said above, I don't like my colors being overridden.

10. I don't like "pure" white backgrounds. The teal suggestion
    made earlier would be good. An off-white would be fine, too.

Rob Stewart                           stewart_at_[hidden]
Software Engineer           
Susquehanna International Group, LLP  using std::disclaimer;

Boost list run by bdawes at, gregod at, cpdaniel at, john at