Hi,
Lit stuff for QuickBook (proposal)
Here's a rough proposal for literate programming in QuickBook.
This was done after a brief chat with Joao on the issue.
First, I must admit that I am not familiar with literate programming.
So, please excuse my naivete. Comments and suggestions very welcome.
Echo
First, we'll need to give quickdoc the ability to enable or disable
the "echoing" of code. [echo off] will will disable printing
(rendering) of code snippets into xml:
[echo off]
#include <iostream>
[echo on] will enable it.
[echo on]
std::cout << "this code gets printed" << std::endl;
The echo directive is modal. By default, QuickBook is set to
[echo on], so previous qbk docs will work as usual. [echo off]
is useful for things you do not want in the docs.
Collectors
Then, we'll have what are called collectors. Each collector has
an identifier (a name). Collectors work like a stack where
successive code snippets (regardless of echo mode) are pushed
into.
[collect a]
char const* s = "this code gets pushed into collector a";
There's a special collector called "none". This special collector
simply throws away everything given to it.
[collect none]
char const* s = "this code will not be collected";
[collect none] is useful when you do not want code to be collected.
Like echo, collect is modal. By default, QuickBook is set to [collect
none], so previous qbk docs will work as usual.
If the collector identifier is in quotes, the collector is
assumed to be a file. Example:
[collect "test.cpp"]
A file collector will collect all successive code snippets into
the specified file. The collect directive with a file id will
empty the file and open it for writing. All open files are closed
at the end of quickbook processing.
Named (non-file) collectors are useful for:
1) building code where snippets are presented in the docs in a
non-linear fasion (e.g. code in the docs are presented out of order).
2) To specify some code snippets that are used more than once
Collector operations:
Copy
Collectors may be copied:
1) Copy src into destination. dest will have the same contents as src.
[copy dest src]
Append
Collectors may be appended to other collectors, pushing the text from
the source collector into the destination collector. Examples:
1) Dump src to dest. dest will be appended with whatever src had.
[append dest src]
2) Dump src into "file.cpp".
[append "file.cpp" src]
Clear
[clear x]
Cheers,
--
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net
-------------------------------------------------------
This SF.net email is sponsored by: 2005 Windows Mobile Application Contest
Submit applications for Windows Mobile(tm)-based Pocket PCs or Smartphones
for the chance to win $25,000 and application distribution. Enter today at
http://ads.osdn.com/?ad_id=6882&alloc_id=15148&op=click
_______________________________________________
Boost-docs mailing list
[email protected]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
