Joel de Guzman <[EMAIL PROTECTED]> writes:
> 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.
Don't feel bad. In some ways, it's still not a well-understood
subject.
> 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).
I like that feature.
> 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.
Hmm. I'm not sure I like having to label each snippet I might want to
process with a collector.
> 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.
When we have a way of labelling examples in quickbook, it would be
nice if there were an automated way to turn the example label into a
filename, e.g. chapter5/example13.cpp
> The collect directive with a file id will
> empty the file and open it for writing.
Each time the filename appears in a directive? Only the first time, I
hope!
> All open files are closed at the end of quickbook processing.
And then what?
In C++ Template Metaprogramming I have examples that I want to
compile, preprocess, build and run, or fail compilation. So far I
don't see any connection to backend processing here. In Litre writing
directives in Python means that I can embed semantics about the
treatment of these snippets, and can extend the way they are handled.
> 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]
Why not [copy src dest]? (from,to) is most natural for most of us, IMO.
> 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.
^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These two things seem contradictory.
Maybe "appended with" is supposed to be the opposite of "appended to?"
> [append dest src]
Anyway, normal English usage is "append A to B" so I suggest you make
that mean "append dest to src." Also, src->dest is more natural for
most of us.
> 2) Dump src into "file.cpp".
>
> [append "file.cpp" src]
Ditto.
> Clear
>
> [clear x]
I don't see any facilities for results processing here. Also Litre
has a lot of less-important features you haven't addressed here; not
sure if you're intentionally leaving those out for now or it's an
oversight.
--
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
