Re: [Boost-users] [Proto] Vector Example Compilation Failure

Subject: Re: [Boost-users] [Proto] Vector Example Compilation Failure
From: Eric Niebler (eric_at_[hidden])
Date: 2011-01-04 12:01:45

On 1/3/2011 1:44 PM, Hossein Haeri wrote:
>>> This is though not encouraged at all and I don't really think 
>>> that the documentations of Fusion and Proto are that nicely 
>>> tied.
>> 
>> Suggestions for improvement are welcome.
> 
> Sure. Here are some suggestions:
> 
> 1) Every now and then in the Proto documentation, you can add a short
> intermezzo which explains which Fusion creature is used in that
> specific point and how.

Fusion is used in *very* few places in Proto. Only unpack_expr and fold
use any part of Fusion, and the reference for those make it pretty clear
the dependence on Fusion.

> 2) You might want to state Fusion as a pre-requisite for proper Proto
> knowledge.

Let me ask you this: what about Proto specifically have you found
difficult to understand without Fusion knowledge? I could focus my
attention there.

> 3) After "Getting Started" and before "Fronts Ends...", you might
> stitch in a short summary of what Fusion is, what it does for Proto,
> and perhaps a quick hand-wavy explanation about the parts of Fusion
> that would be handy in development using Proto. Obviously, this will
> have links to appropriate corners in the Fusion documentation.

I'm not (yet) convinced it's necessary, and I certainly don't want to
document Fusion even in hand-wavy terms. It's a maintenance burden to
have to keep it in sync with the actual Fusion documentation.

I wish our document toolchain made cross-linking in our docs easier.
That's the way to go, IMO.

> On the other hand, the documentation of Fusion is rather a reference
> manual and you'd usually not learn how to program using a library by
> reading the mere reference...

Yeah, the Fusion docs could use more users'-guide-ish docs for its
high-level architecture, concepts, and common usages.

-- 
Eric Niebler
BoostPro Computing
http://www.boostpro.com