Thomas Guest wrote:
Joel, JoÃo,
I think the model Joel presents, based on collectors, looks conceptually
neater. The documentation drives the source code. I would really like to
see an example of a non-trivial literate QuickBook program to back-up the
proposal. I cannot determine if the scheme is sufficient and complete,
but, as I said, it looks neat.
I'm not sure about a non-trivial literate QuickBook program, but
here's an attempt. This is based on Phoenix2's docs in the
Starter Kit section. See attached. If you look at the Phoenix
docs (http://tinyurl.com/5zjhc), you'll notice that I can reuse
the collected snippets for the rest of the section.
I can see more clearly how the second model (presented by JoÃo) would
work, but I don't like adding the snippet delimiters in comments. It
cuts across the Doxygen comment processing. Remember also that the
comment syntax will be different for different source modes. That said,
James Fowler has already gone some way towards implementing inclusion
of snippets.
I agree. When Joao and I had the chat, I wasn't quite anxious
about the include snippet proposal. I didn't have a strong
case against it at the time and thought that both solutions
are orthogonal anyway. Now, it seems that you provided a
strong case against it: that 1) Qbk needs to know something about
the target language and each markup syntax will be different for
different langauges. This is unwieldy. 2) I too do not like
special tagged comments in my source code. In that sense, I am
not quite fond of Doxygen, in fact.
Regards,
--
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net
[echo off]
[collect copyright]
/*=============================================================================
Copyright (c) 2001-2004 Joel de Guzman
Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
http://www.boost.org/LICENSE_1_0.txt)
==============================================================================*/
[collect include1]
#include <iostream>
#include <boost/spirit/phoenix/core.hpp>
[collect using1]
using namespace boost::phoenix;
using namespace std;
[collect prefix1]
int
main()
{
[collect suffix1]
return 0;
}
[echo on]
[collect none]
[section:val Values]
Values are functions! Examples:
val(3)
val("Hello, World")
The first evaluates to a nullary function (a function taking no arguments) that
returns an `int`, `3`. The second evaluates to a nullary function that returns
a `char const(&)[13]`, `"Hello, World"`.
[h2 Lazy Evaluation]
Confused? `val(3)` is a unary function, you say? Yes it is. However, read
carefully: /"evaluates to a nullary function"/. `val(3)` evaluates to (returns)
a
nullary function. Aha! `val(3)` returns a function! So, since `val(3)` returns
a
function, you can invoke it. Examples:
[collect values_example]
cout << val(3)() << endl;
cout << val("Hello World")() << endl;
[collect "values.cpp"]
[append "values.cpp" copyright]
[append "values.cpp" include1]
[append "values.cpp" using1]
[append "values.cpp" prefix1]
[append "values.cpp" values_example]
[append "values.cpp" suffix1]
(See [@"values.cpp"])
