Jo�o Abecasis <[EMAIL PROTECTED]> writes:For this the (proposed) include command would become:
[include file.ext id]
where id is an optional parameter that identifies a snippet;
Do you mean a collector?
id only identifies a portion of the included file as illustrated later in the post.
file.ext is the name of the file to include and ext is used to determine the filetype.
Quickbook files are inserted verbatim and interpreted as quickbook, code files are inserted as syntax-colorized code.
How do you determine whether it's QuickBook or code?
The file extension can be used for that. We could also agree on syntax to override the file extension. For instance, we could reuse the syntax highlighting markup:
[include [c++] file.py id]
Inserting a snippet of a quickbook file could be used to cause a quickbook snippet to be inserted as syntax-colorized quickbook code.
Is there a way to leave out boilerplate code that would not be appropriate in the docs? For example, copyrights, standard #includes for which you've already given the user lookup rules, workaround code for broken compilers, etc.? Ah, I see below...
When inserting snippets from files, quickbook searches in *comments* for the snippet delimiters. For instance,
* sample.cpp
#include <iostream>
int main() { // qbk [snippet print]
std::cout << "this code gets printed" << std::endl;
// qbk [endsnippet] }
Well, these can obviously be processed out fairly easily via automation for presentation to readers, so that's nice. But there should be a way to "continue" or "reopen" a snippet.
I suppose reusing the id could append to the snippet.
// qbk [snippet print]
... code to be printed ...
// qbk [end snippet]... something else ...
// qbk [snippet print]
... some more code to be printed ...
// qbk [end snippet][including] print would generate
... code to be printed ...
... some more code to be printed ...
* sample.qbk
[/ ... ]
[include sample.cpp print]
[/ ... ]
I like this idea. But there's still no place to encode how the included files should be processed. I realize you can list them separately in a Jamfile or and you can even use globbing to find them and give them default processing, so maybe for this sort of example that's not so bad.
I figured that because the code files are kept separately, all pre and post processing can be left out of the docs.
Anyway, I agree that we still need a general solution for the external processing of code used in the docs and we'll have to consider how that solution can be applied here too.
We also need some way to process inline code as Joel has been proposing, so that there's a way to write testable examples without breaking the flow. Otherwise people will just end up writing lots of short (wrong) examples with no tests ;-)
Right, that's what we're trying to get at with both approaches, even though we only presented how to extract and generate the code up to now...
Jo�o
------------------------------------------------------- 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
