Boost logo

Proto :

Subject: Re: [proto] Proto documentation, tutorials, developer guide and general Publis Relations
From: Eric Niebler (eric_at_[hidden])
Date: 2010-12-04 12:01:40

On 12/4/2010 10:42 AM, joel falcou wrote:
> Hey,
> recently I have been promoting Proto to a few fellow coworker in some
> academic circles as well as in
> some industrial contexts. Most of these evangelisation process turned
> quite well but I felt a lot of time
> that something wasn't clinking as it should and I think it's partially
> because of the way proto presents
> itself and how the docs examples and tutorials are structured. So here
> is a few remarks and some
> ideas on how to improve it.
> 1/ Proto describes itself as "Proto is a framework for building Domain
> Specific Embedded Languages in C++. It provides tools for constructing,
> type-checking, transforming and executing expression templates". A lot
> of people I spoke too where wondering what expression templates were and,
> as non-C++ expert, as honestly no clues what it was about. Others jumped
> on the fact that "oh it enables some lazy evaluation idiom in C++ ?".
> Few were acustomed to the EDSL idom. So, I wonder if we could not touch
> more potential users by stating it in a way "lazy evaluation" appears.

Something along those lines would be a big improvement. I've gotten
better at explaining Proto since I wrote those docs, and they could use
a major facelift.

I still like the fundamental idea of structuring the users guide around
the idea of Proto as a compiler construction toolkit, with sections for
front-end, intermediate form, and back-end. But before we get to that,
there should be a Not-So-Quick Start with examples that gets people going.

> 2/ What's the long term plan for context classes ? I remember discussign
> their removal but will it happen (at least from the doc) ?
> I spend quite a time demonstrating and reteaching transform over context
> to a lot of people. I'll gladly see them
> deprecated in 1.46 and maybe ditched in 1.47 or is there any reson to
> keep them ?

I have a long-standing work-item to go through the docs and examples and
move them all from contexts to transforms. The contexts must go.

> 3/ The documentation on-going example of the calculator is OK but it
> lacks somethign between this and the full fledged, impressive
> small lambda or futures sampels at the end. I noticed a huge gap between
> the toy calculator and code people have to really write with
> proto. On the other hand, the Boost'con 2010 talk examples of map_assign
> was a real gem as it was simple enough to be grokkable by
> everybody and yet demonstrated a lot. I think it should be in the
> documentation instead of as a sample at the end. I remember
> thinking "why it is not detaile dlike that in the doc" during your session.

Good point. Could be part of a Not-So-Quick Start.

> 4/ Maybe more diverse examples coudl eb turned into full fledged,
> detailed, step by step tutorial. map_assing


> , some kind of simpel lazy
> computation stuff (like the numerical integration sampel form Veldhuizen
> paper), a larger example with a transform not tied to the grammar (a lot
> of people assumed it could not be done),

Yes, this an some other newer features are not described in the users'
guide at all. That includes sub-domains, per-domain control over
as_child and as_expr, external transforms, and now the expanded set of
functional callables.

> etc ... Thomas Heller and I
> were brainstormign a bit and mayeb we can actually get a list, code it
> and write the tutorial over. I can also offer internals of our SIMD code
> or even from Quaff for a tutorial on how having proto enabled
> intermediate representation is useful or on how to do pattern matchign
> on AST.

Any and all contributions are welcome. But no "assing" please.

> 5/ Finally, this is starting to look like the Spirit site.

What is "this"? Are you referring to I'm pretty committed
to finishing the article series I started there, and it wouldn't be
right to move it elsewhere at this point.

> What about a
> proto blog/website where articles liek this or sample code could be
> detailed, introspected and published ?

Perhaps after I finish the Expressive C++ article series on, I could continue it elsewhere.

Eric Niebler
BoostPro Computing

Proto list run by eric at