Subject: Re: [boost] Improving Boost Docs
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-08-16 15:03:38
On 8/16/17 1:25 AM, Gavin Lambert via Boost wrote:
> On 16/08/2017 17:39, Robert Ramey wrote:
>> regardless of the details, just the look of the diagram is pretty
>> intimidating. On the the other hand, once you the tools, scripts, etc
>> installed, it's just a matter of calling boost build so everything is
>> hidden. This makes it pretty simple ... until it doesn't which is
>> just about always.
>> I actually like the whole system and I think it's pretty well suited
>> to boost. BUT, the combination with boost build and the desire to
>> hide all the complexity makes it more difficult to use rather than
>> easier. I think if we could work on this, we might persuade
>> developers to stick with it rather than looking for alternatives.
> So it needs better meta-documentation? :)
LOL - very clever. But I actually look at the problem in a different
way. It's my view that when something is hard to describe/document it's
a symptom that there is design error somewhere. So that it's time to
step back and see what mistake you made which leads to something too
complex to understand. With the boost documentation system there are
couple of suspects:
a) The embedding of the complex tool chain into bjam. Of course this is
technically doable and results in a very slick - "do what I mean
interface" (DWIM tm robert ramey). But with something this complex no
one can anticipate all the exceptional cases and when they occur, the
system leaves one bereft.
b) The inclusion of all the specialized tags for C++ like class, struct,
is meant to automate the production of boiler plate output for those C++
constructs. I understand the appeal of this - we're computer
programmers and want to automate everything - but in this case it's a
bridge too far. quickbook doesn't use these - a good choice in my
opinion. A few hand edited boost book do uses these but the results are
not satisfying in my opinion. To improve them, one would have to wade
into XSL language - a place were few people want to go.
In short, better documentation of the toolset wouldn't hurt, but I don't
think it would solve the whole problem.
> Unsubscribe & other changes: