Boost logo

Boost :

From: Thorsten Ottosen (nesotto_at_[hidden])
Date: 2005-07-14 11:08:52

David Abrahams <dave <at>> 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
> reasonable.


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.*checkout*/boost/boost/libs/range/doc/rang

>> >> 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
> own.

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
> up).

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.

best regards


Boost list run by bdawes at, gregod at, cpdaniel at, john at