Jo�o Abecasis <[EMAIL PROTECTED]> writes:
> Hi!
>
> Joel de Guzman wrote:
>> 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.
>
> I'll start with the same caveat emptor, I'm not familiar with literate
> programming...
>
> In our chat, Joel and I also discussed another approach that complements
> Joel's proposal in this regard. This is the possibility of including
> code snippets maintained in a separate source file (as opposed to
> collecting code fragments in the docs).
>
> 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?
> 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?
> 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.
> * 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.
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 ;-)
--
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
