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

From: David Abrahams (dave_at_[hidden])
Date: 2004-09-29 17:58:30

"David B. Held" <dheld_at_[hidden]> writes:

> Eric Niebler wrote:
>> 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.
>> [...]
>
> I think it looks great!  Good work, guys.  I agree with Dave that code
> should be indented for better readability.  I'm ambivalent about colors,
> but I like blue, so I don't have a problem with the colors chosen.  

Y'know, I like blue too, but it shouldn't be used for non-links.
Section headings should be black, just like the rest of the non-linked
text.  Black on white reads much more easily (yes, according to
research) and that applies to headers as well as body text.

> I also like the idea of collecting all the documentation into one
> large hyperdocument.  It makes Boost look more like a serious
> collection of libraries rather than a hodgepodge thrown together.
> Making all the docs look consistent goes a long way towards that.  I
> also agree with Thorsten that it would be nice to get an automagic
> syntax highlighter in the toolchain that preprocessed code blocks to
> produce some nice color-highlighted html.  It would be really nice
> if it emitted code on a fairly fine-grained scale (lots of syntactic
> elements) so that there is plenty of flexibility for writing custom
> css configs for your favorite syntax-highlighting setup (that way,
> ambitious people could view the code in the docs in the same scheme
> that, say, their IDE uses).  Of course, I have no idea how much work
> that would be, and I'm not exactly in a position to volunteer the
> time right now, but it seems to me that Wave must already have some
> of the capability, given that it knows enough C++ to do
> preprocessing.

You have to be careful about that.  We could easily make things worse
for many people by making the wrong color choices.  In that case,
black would be better.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com