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