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

From: Douglas Gregor (gregod_at_[hidden])
Date: 2003-01-19 21:48:48

On Sunday 19 January 2003 08:25 pm, Beman Dawes wrote:
> 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?

If the library documentation is in the BoostBook format, just make sure the 
Boost documentation includes the BoostBook source (e.g., by adding an 
appropriate xi:include element to boost.xml).

If the library documentation is in HTML, the developer needs to add a library 
description to the file boost-sandbox/libs/documentation/examples/boost.xml. 
A library description looks like this:

  <library name="Compressed Pair" dirname="utility" html-only="1"
           url="../../libs/utility/compressed_pair.htm">
    <libraryinfo>
      <author>
        <firstname>John</firstname>
        <surname>Maddock</surname>
      </author>
      <author>
        <firstname>Howard</firstname>
        <surname>Hinnant</surname>
      </author>
      <librarypurpose>Empty member optimization</librarypurpose>
      <librarycategory name="category:data-structures"/>
      <librarycategory name="category:misc"/>
    </libraryinfo>
  </library>

I think the above is relatively self-explanatory. The library category names 
are in the same file (boost.xml), and are each defined like this:

        <librarycategorydef name="category:string-text">
          String and text processing
        </librarycategorydef>

> 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.

That's mostly an issue with the way I'm using DocBook. Will fix.

> * 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.

Will do. Sprucing up the headers has been on the task list for a while, but 
nobody has yet to take on the challenge :)

>     -- Footer should have a "revised" date. I like the horizon rule, too.

A "generated" date would be easy; a "revised" date isn't so easy, because it's 
not trivial to figure out when something used in the list changed.

>     -- 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.

The footer is much better than the header in this regard, because it actually 
gives names. 

> * 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.

Done. I think it does look better.

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

I'm not sure. XSLT does have an "indent" property when transforming to another 
XML document, but AFAIK it's not considered safe to use when spacing is 
important. And spacing _is_ important, especially within the reference 
documentation.

> 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.)

I'm not expecting this page to go into CVS, but to be autogenerated nightly 
along with the rest of the documentation. 

        Doug