[Boost-testing] Re: QuickBook Includes and Literate Programming [Was Re: Dynamically Loadable Syntax Highighters [ Was Re: [ANN] QuickBook 1.0 now in boost/tools]]

From: David Abrahams (dave_at_[hidden])
Date: 2005-03-12 19:18:35

Joel de Guzman <joel_at_[hidden]> 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
> Boost-docs_at_[hidden]
> Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
>

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com