Re: [boost] [Range] No Reply?

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

right.

so you propose an extra bullet like

*Models*

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

http://cvs.sourceforge.net/viewcvs.py/*checkout*/boost/boost/libs/range/doc/rang
e.html

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

<g>

> 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

-Thorsten