From: Thorsten Ottosen (nesotto_at_[hidden])
Date: 2005-07-14 11:08:52
David Abrahams <dave <at> boost-consulting.com> writes:
> > It's not like I don't agree, it's just that it is already said in the
> > introduction.
> People will use this as reference docs. Don't expect them to read
> cover-to-cover. They will jump to the concept definition, and that's
so you propose an extra bullet like
- all standard containers
- std::pair<iterator,iterator> where iterator is an XXX iterator
- builtin arrays
for each concept?
> Go to the boost web page. Follow the link in the left column to CVS.
> There will be a link to CVSWeb. Browse.
>> >> Sorry, but that's not a definition of anything.
> > The sentence says that each type of iterator induces a type of range.
> It's still not a definition of anything.
> Please try not to make this
> so difficult for me. Going back and forth like this takes a lot of
> energy from both of us; we'd both be done sooner if you'd resist less
> (or if I just gave up).
please just tell me how you would write it. I'll add your definition
to the docs.
> >> I don't know what the right title is first try to answer the question
> >> I asked:
> >> You need to rename this page. What is it really describing?
> >> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> So, what is the page really describing? Please just try to nail down
> in a few sentences, what you are trying to tell the user on this
> page. That will tell us what the right title is.
It contains synopsis and from the synopsis you can jump to the
definition of the function/metafunction in question.
maybe it should just be called Synopsis & Reference?
> >> then no, it doesn't make it clear that they "just work." It claims
> >> that the library gives me the *means* to make them "just work." So
> >> I'm left asking, "how do I do that?"
> > have you read the introduction *and* its example ???
> Do not expect users to read cover to cover. Introductory and tutorial
> material can be considered non-normative, and can leave out some
> details if absolutely necessary, but the concept definitions are part
> of the reference and the reference documentation needs to stand on its
yeah. would the "models" bullet help?
> >> Also, IIUC, this and other mentions of null terminated strings need
> >> to be removed now.
> > yes, when I get the time or when somebody volunteers (1.33 is out of the
> > question).
> If the code has changed, you have to change the docs before 1.33.
> Otherwise, you have to do the change after 1.33. I assumed that the
> former was the case.
the former is the case.
> > I don't have the feeling that the range docs are totally
> > inappropriate, they could probably be better, but I wonder if it is
> > worth our effort to spend days on them; our time could probably be
> > better spend.
> Boost documentation is easily as important as Boost code; it is
> absolutely worth effort to spend days on it. The quality of our
> documentation (or lack thereof, in places) is becoming a serious
> barrier to adoption (yes, I have empirical data to back this claim
the boost documentation is in general good IMO.
> This stuff isn't easy; I have been writing the Parameter library
> tutorial for about a week now.
looking forward to read that.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk