(take two, since sourceforge doesn't seem to favor .zip attachments...)
Robert Ramey wrote:
As one who recently started working with BoostBook, I would answer your "is it ready" question with an absolute "maybe"... I've found it to be very useful, if still a bit rough around the edges. I would highly recommend using QuickBook. While it doesn't quite do everything yet, you can '''escape out''' to straight BoostBook xml to handle most anything exotic. The syntax for QuickBook is, IMHO, more appropriate for C++ documentation, and it should simplify improving functionality while maintaining a consistent overall format within Boost documentation.I'm looking ahead to moving serialization library to boost book. I'm a little uncertain as to its status.
Is this thing ready to use for "the rest of us" as opposed to boost book developers?
As an example, I converted a few sections (overview.html / tutorial.html / bibliography.html) of the serialization docs from Boost 1.3.2. The source in QuickBook form can be seen at http://www.openseaconsulting.com/boost/doc/ser_tutorial.qbk, and the resulting html after running through the BBv2 QuickBook/BoostBook is at http://www.openseaconsulting.com/boost/doc/html/index.html. There are a few awkward spots, like the bibliography (QuickBook doesn't like anchors inside list elements - yet ; ) and invisible underlining (although maybe that's a style sheet issue). However, there are also some noticeable improvements, like automatic generation of the "contents" sections and much better support (both in the source .qbk and the generated html) for including C++ source code. In any case, this should give you a good way to evaluate QuickBook for boost::serialization.
It appears that you are not using Doxygen for boost::serialization. That may actually make things easier at this point, as the Doxygen integration with BoostBook is, from my recent experience, a bit frustrating. It works (mostly) and will probably get much better over time, but it's perhaps the least "ready" piece of the BoostBook family. If you skip Doxygen and stick to QuickBook, you'll probably have few problems, and whatever problems arise should be much easier to handle. I'm not recommending avoiding Doxygen in general - I'm using it for my own projects - but boost::serialization is a little different since you already have existing docs which should move easily to QuickBook without having to become a "boost book developer".
I don't know about that (is anyone working on it?). My guess is that it (or something similar) will be in there eventually. Based on the way you set up "serialization/doc/contents.html", it looks like it should be fairly simple for someone who knows the inner workings of DocBook and BoostBook xsl transformations. Or a very educational and potentially masochistic exercise for those yet to be initiated into the secret forms...What is the prospect for including the J Turkanis Expand/Collapse index window?
- james
-- __________________________________________________________ James Fowler, Open Sea Consulting http://www.OpenSeaConsulting.com, Marietta, Georgia, USA Do C++ Right. http://www.OpenCpp.org, opening soon!
------------------------------------------------------- SF email is sponsored by - The IT Product Guide Read honest & candid reviews on hundreds of IT Products from real users. Discover which products truly live up to the hype. Start reading now. http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
