Joel de Guzman <[EMAIL PROTECTED]> writes: So nobody else thought this was important? Doesn't anyone else see the deep connection between two of our major infrastructure areas, testing and documentation?
[I quoted everything here for the benefit of boost-testing readers] > 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 > -- 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
