[boost] Re: [Boost-docs] Integrating BoostBook documentation with HTMLdocumentation

From: Beman Dawes (bdawes_at_[hidden])
Date: 2003-01-19 20:25:08

At 02:30 PM 1/19/2003, Douglas Gregor wrote:

 >The alphabetized/categorized list of libraries generated from the 
BoostBook
 >documentation now includes all libraries that have (only) HTML
 >documentation, so it is now possible to replace boost/libs/libraries.htm
 >with the generated doc/html/libraries.html. Here is the HTML:
 >
 >  http://www.cs.rpi.edu/~gregod/boost/doc/html/libraries.html
 >
 >I have a script that regenerates the all of the current documentation
 >formats
 >(HTML, PDF, man pages, XSL formatting objects, and DocBook---see the link 

 >above) that will be run nightly following updates of the Boost and Boost
 >Sandbox CVS repositories, so the current CVS documentation will be
 >available from the above URL. I'd like to make a "CVS" link to this URL
 >under the "Documentation" header on the Boost main page. Objections?

I'd like to see a bit more refinement first, and understand how the 
maintenance works.

Let's take the last first. What does a developer do to add a new library?

As far as refinement goes:

* Why the bloat of breaking libraries.html up into multiple files? For me, 
at least, this reduces the quality of the browsing experience.

* If for some reason it is really desirable to split the one file into two, 
the second one should have a meaningful name.  ch01s02.html gives you no 
clue as to what "next" is linking too.

* The navigation header and footer need more work, IMO:

    -- Some color and general site navigation help. If you don't like the
       usual Boost intermediate level page header (see the current
       libraries.htm), design another one. But the page needs something
       to give it a bit of life, identification with Boost, navigation
       back to home, etc.
    -- Footer should have a "revised" date. I like the horizon rule, too.
    -- Personally, I dislike "prev" and "next" links in general, and
       particularly those that give no indication of what they are linking
       to. Hovering the cursor to see the link URL helps a bit, but only a
       little.

* Have you tried single spacing the alpha and by category lists? The old 
single spacing seems a tiny bit easier to scan, although that is obviously 
very subjective.

* The formatting of the HTML isn't very human reader friendly. Would it be 
possible to do a bit of formatting?

Have you check to verify there won't be any CVS "churn" once this becomes 
something that is checked into CVS? (Unless, of course, there is a real 
change on the page.)

The content looks good, but I think a bit more work on the presentation is 
needed.

--Beman