James Fowler <[EMAIL PROTECTED]> writes: > 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.
Yes! > 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. I have been using docutils/ReStructuredText (http://docutils.sourceforge.net/rst.html) to get the same effect. All of "C++ Template Metaprogramming" and the MPL docs were done with docutils. I haven't looked at the QuickBook source code yet, but from everything I've heard, I think I'd rather be using that. That said, I'm pretty sure ReStructuredText is more mature than QuickBook. There is built-in support for all kinds of constructs in ReST, although admittedly many of these can probably be handled as well by escaping to BoostBook. How is QuickBook's unicode support? We also need to pay attention to other kinds of processing. I implemented a "literate programming system" called LitRE ("Literate REstructuredText") that can extract and test examples. This proved absolutely crucial in ensuring that our examples were correct (it found lots of bugs), something we've had problems with at Boost in the past. Considering that we have quite a few errata at http://www.boost-consulting.com/metaprogramming-book.html anyway I am sure glad we used it! I've attached the ReST/LitRE source to our sample chapter "A Deeper Look at Metafunctions" for your amusement. ReST comments are indented blocks beginning with '.. ' in the first column. The ReST comments beginning with '@' contain embedded python code for running the tests. LitRE is built around a stack of code examples, the top element of which is called "example." Some of what you'll see in there is code to manipulate the snippets to make them acceptable to the compiler in context. For example, a code fragment may need a function body around it in order to compile: Now, if we want to compute the force exterted by gravity on a 5 kilogram laptop computer, that's just the acceleration due to gravity (9.8 m/sec\ :sup:`2`) times the mass of the laptop:: quantity<float,mass> m(5.0f); quantity<float,acceleration> a(9.8f); std::cout << "force = " << (m * a).value(); .. @example.wrap('#include <iostream>\nvoid ff() {', '}') compile('all', pop = 1) I don't claim this is an ideal system. It would be especially nice to have an editor that would fold away the LitRE comments during regular editing. Emacs has a ReST mode; I'm sure that could be enhanced. Speaking of Maturity: ***** We need an Emacs QuickBook mode!! ***** (and Vim or whatever. I'm an Emacs user) -- Dave Abrahams Boost Consulting www.boost-consulting.com ------------------------------------------------------- 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
