[Boost-users] Re: Converting from const tonon-constwithiterator_adaptor

From: David Abrahams (dave_at_[hidden])
Date: 2004-01-09 08:26:50

"Keith MacDonald" <boost_at_[hidden]> writes:

> We're clearly on different wavelengths here.  I've often found that if
> someone asks an apparently dumb question about my software, or its
> documentation, then it's better to improve the area in question, rather than
> tell the person he's not using or reading it correctly.  

I'm 100% in agreement with that.  You *weren't* reading it correctly,
but it's clearly the fault of the documentation.  The problem I'm
having is seeing how to keep users from feeling misled by the
statement that apparently misled you.  Even if iterator_adaptor can be
used to adapt non-iterators, that *is* a corner case.  We'll be
telling people to use iterator_facade when they're not starting with
something very much like the iterator they want to end up with.
That's just good advice.  Should we say, "think hard about it and
remember that pointers are iterators too?"  I don't think so.  I think
it'd be better to just show your linked list example implemented with
both iterator_facade and iterator adaptor in the detailed user-level
examples that we'll provide.  And we can't do that on the front
page.

> I was only trying to be helpful.

I'm sorry, I realize that part of your post was trying to be helpful,
but I have a hard time seeing how your veiled accusation that we're
keeping the workings of the library secret so that we can sell books
is anything other than a cheap shot.  

>> > In my opinion, for what it's worth, the documentation seems to be
>> > aimed at the developers of the library (so you're all singing from
>> > the same hymn sheet), rather than potential users.
>>
>> How many times do I have to repeat that
>>
>>   We're working on the docs.  That document is the standards proposal,
>>   but the Boost (user-level) docs aren't complete yet.
>>
>> ??

I'm sorry that I lost my patience with you saying that user-level docs
are needed, but c'mon, the library isn't released yet, and I had
already told you we were still working on the docs (twice!) in this
very thread.  I think it's fair to let me know that the docs could be
improved, but before the library has even entered a Boost release this
amounts to harping on it.

>> > Clearly, both audiences need to be catered for - unless it was just
>> > an academic excercise.  Of course, if you're already writing the
>> > text book for us users, then I completely understand the advantages
>> > of impenetrable free documentation ;-)
>>
>> I'm providing free software *and* free documentation as time allows; I
>> really don't need to have my motivations insulted that way.  A smiley
>> doesn't make it funny.
>>
>> -- 
>> Dave Abrahams
>> Boost Consulting
>> www.boost-consulting.com

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com