Hi Y'all,
Now that we all agree to add file inclusion support for QuickBook, It would be natural that such a mechanism can also include program source files (c++, python, etc.). This would be a first step to solving the nagging problem of synchronizing the docs and the source code (e.g. tests, examples).
One concern is that, typically, in tutorials, we present the code in pieces. Perhaps we really ought to go into Literate programming land, turning the table around (i.e. the docs drive the source code). We need a scheme where QuickBook code fragments can be assembled into actual source files that can be compiled/executed/tested.
Here's an email from Dave Abrahams:
Hi Joel,
Enclosed please find the code for litre, the LITerate REstructuredText system.
If you look at the .rst source for any of our chapters (all of which are available in the reviewer's area of the book's website and one of which is enclosed) you'll see these special comments that begin with '@', e.g.:
.. @compile()
Litre works on a very simple principle: using a special "writer" -- a backend component of the ReST processing system -- each code example gets pushed onto a stack as it is encountered, and each "litre directive" (the special comments) is Python code for handling the examples. This writer is highly specialized because it basically ignores everything that doesn't appear in a literal block. It would probably be easy to replace the writer with a quickbook processor. Sometimes the litre code says:
.. @ignore()
which just pops the top item on the stack. Litre injects Python symbols directly into the environment in which this code is executed at module scope so names like "compile" and "ignore" can be used without qualification.
There are a few additional tricks that litre plays to deal with typographical conventions of the book:
lines contatining just elipses in code examples get commented out so:
...
becomes
/* ... */
and all italic text in code examples is presumed not to be real code, but some stand-in text to be replaced by real code, so it too is commented out.
Litre provides a way to replace the nth such bit of text with specific code for testing purposes.
litre.Writer is a generic litre writer and cplusplus.Writer is a subclass implementing the logic for interpreting C++ examples.
Sorry for the rambling rush of info. :)
-- Dave Abrahams Boost Consulting http://www.boost-consulting.com
-- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
------------------------------------------------------- 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
