Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-10-12 04:57:01

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Andrew Hundt
> Sent: Friday, October 11, 2013 5:46 PM
> To: boost_at_[hidden]
> Subject: Re: [boost] Improving Documentation
> 
> On Friday, October 11, 2013, Mathias Gaunard wrote:
> 
> > On 11/10/13 00:07, Andrew Hundt wrote:
> >
> > I believe part of the problem is that everything is blue. For
> > instance, on
> >> the boost.lockfree page:
> >>
> >> http://www.boost.org/doc/libs/**1_54_0/doc/html/lockfree/**
> >> reference.html#header.boost.**lockfree.policies_hpp<http://www.boost.
> >> org/doc/libs/1_54_0/doc/html/lockfree/reference.html#header.boost.loc
> >> kfree.policies_hpp>
> >>
> >>
> >>     - The following words are blue:
> >>        - namespace, template, bool, struct, capacity, template, typename,
> >>        allocator, class, fixed_sized, queue, spec_queue, stack
> >>
> >
> > It's clearly not the same shade of blue though. The links (capacity,
> > allocator, fixed, queue, spec_queue, stack) are closer to a greenish blue.
> > Do they appear difficult to distinguish to you?
> >
> > Maybe the color palette could be changed.
> 
> 
> It isn't just me. I believe two others in this email chain mentioned it took them a while to
figure out too,
> and I have had to explain it to other users who are not on this list. The shades certainly don't
"pop" and it
> could just be more syntax highlighting. There isn't anything distinguishing it a a link when you
just look at
> the page and imagine not already being familiar with this documentation layout. Doxygen and other
> documentation tools don't really have anything like it.

Ok - if you have some concrete proposals, please experiment with your 

\boost-root\doc\srcboosbook.css

the colors are defined in this section

     /* Links */
        a, a .keyword, a .identifier, a .special, a .preprocessor
        a .char, a .comment, a .string, a .number
        {
            color: #005a9c;
        }

        a:visited, a:visited .keyword, a:visited .identifier,
        a:visited .special, a:visited .preprocessor a:visited .char,
        a:visited .comment, a:visited .string, a:visited .number
        {
            color: #9c5a9c;
        }

        h1 a, h2 a, h3 a, h4 a, h5 a, h6 a,
        h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover, h5 a:hover, h6 a:hover,
        h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited
        {
            text-decoration: none; /* no underline */
            color: #000000;
        }

There are some useful links to colors in this recent post about coloring text in Quickbook.

https://svn.boost.org/trac/boost/ticket/5860#comment:11

You could post 'Andrew's Favorite Colors' for user comment?

> Yeah, it would be great if everything had micro examples at the bottom of each page but often the
only
> thing that exists is a unit test. While it isn't a great situation it would be better than
nothing.

IMO, library docs are not complete without at least one working example, including code snippets in
the main text and link to the actual code so users can read and download easily.

Cheers

Paul