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
_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
