Re: [Boost-docs] Re: Boost Book Status

[James Fowler]

I looked at the conversion you did for the serialization documents and can only ask - Why did you stop? They look great to me. This gives me strong motivation to make the switch. Or perhaps the right question was why did I start?  I did what I hoped would be enough to give you just that motivation : )   While in some ways I might actually enjoy going through and converting existing docs to QuickBook,  the connection between doing all that myself and paying the rent seems a bit tenuous, and worse yet it might arouse suspicion that I lack the requisite virtues of a great developer...  OTOH, I have a strong desire to see improvement to (even though it's already impressive) the consistency and "polish", if you will, of Boost as a whole.  I think QuickBook will be one of the catalysts for such improvement.  While I haven't done anything (yet) with the Boost Serialization library,  I have substantial experience with the internals of similar systems, which has given me a deep appreciation of their usefulness and of the challenges in building them well.  Your library actually made it through the formal Boost approval process, so I'm presuming that it is good stuff ; ). So consider the following: You wanted to know if QuickBook was ready for "the rest of us" You are obviously a legitimate and valuable Boost contributor The Boost Serialization docs look like an ideal test case for the feasibility of converting HTML to QuickBook format, but you've expressed (if I may paraphrase a bit) justifiable concern about jumping in without some evidence that your time would not be wasted I want to see all Boost contributors using a consistent foundation which just works so they don't have to worry about it, focusing on their libraries instead of fighting the tools, and I think QuickBook is a key part of that foundation Mix all that together and this comes out : my motivation is that I want to see _you_ learning and using QuickBook from now on and _liking_ it.  For now the possibility that the existing docs for Serialization get moved to QuickBook is a welcome, but secondary, benefit.   I want you to be so happy and successful with it that when the next guy comes along, he won't need such demonstrations.  So what motivation would you have if someone else just did it all for you? : ) As you can imagine, I'm in love with the left hand navigation pane. Jonathon Turkanis submitted a generic solution which I was hoping would have been integrated into boost - book by now. After digging through the history of Jonathon's enhancement, I too was surprised that the process of integrating it seems to have stalled.   However, the potential for that kind of capability is one of the major reasons I'm so interested in getting more of the Boost developers using tools like QuickBook.  We can introduce new features across the board as enhancements to the QuickBook->BoostBook->... process without changing the process of writing the documentation itself. Admittedly one could (and perhaps some have) make similar statements about using BoostBook format directly, which raises questions about why more hasn't happened already, and more importantly, why should QuickBook be different?  Two things come to mind.  First, the QuickBook format offers a much simpler, purpose-oriented form of _expression_ for writing Boost docs than raw BoostBook xml (or, as I hope that sample demonstrated, even straight html).  Second, the task of enhancing the output from QuickBook is more widely accessible to interested participants from the Boost community (being in C++) than dealing with the maze of BoostBook/DocBook xsl transforms.  Most of the time, QuickBook is just a better "fit", allowing just the right abstractions without cluttering things up with unnecessarily complex, verbose markup. In terms of that specific enhancement (the left hand navigation pane), I don't know how hard it would be to incorporate into BoostBook.  However, it may prove to be a more manageable task to integrate this into QuickBook's output rather than BoostBook in general.  I might take a crack at it once I get some current projects wrapped up. Its very important to me to avoid becoming a "boost book developer" Absolutely.  IMHO, until a Boost tool can reliably support the development and use of Boost libraries without requiring any knowledge of the tool's internals,  it just ain't there yet...  Nobody should have to become a "boost book developer" to use QuickBook. - james -- __________________________________________________________ James Fowler, Open Sea Consulting http://www.OpenSeaConsulting.com, Marietta, Georgia, USA Do C++ Right. http://www.OpenCpp.org, opening soon!