Ok, if the Boost style documentation is too simple, and docs like Spirit are too cute, what is a nice, happy median? If we're going to demand uniformity in licensing, should we also demand more uniformity in documentation? I think a single documentation style across Boost would make it even easier to learn new libraries. I recently found it very difficult to find the information I wanted about the Boost.Test library, as well as Boost.Preprocessor. What can be done about these issues? Dave --- Outgoing mail is certified Virus Free. Checked by AVG anti-virus system (http://www.grisoft.com). Version: 6.0.701 / Virus Database: 458 - Release Date: 6/7/2004
"David B. Held" <dheld@codelogicconsulting.com> wrote in message news:cabt50$sl9$1@sea.gmane.org...
Ok, if the Boost style documentation is too simple, and docs like Spirit are too cute, what is a nice, happy median? If we're going to demand uniformity in licensing, should we also demand more uniformity in documentation? I think a single documentation style across Boost would make it even easier to learn new libraries. I recently found it very difficult to find the information I wanted about the Boost.Test library, as well as Boost.Preprocessor. What can be done about these issues?
Dave
Just wondering, what specifically couldn't you find in Boost.Test Docs? And how different fomat would help? you? Gennadiy.
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> wrote in message news:cacotf$cl5$1@sea.gmane.org...
[...] Just wondering, what specifically couldn't you find in Boost.Test Docs?
A reference to the BOOST_XXX macros (like CHECK, CHECK_EQUAL, etc.). I finally realized you have to look at the headers, but that doesn't seem like it should be necessary. Also, I couldn't find a reference for the command line arguments (log_level, etc.).
And how different fomat would help?
Having a section on the macros would help. Having a section on the command-line arguments would help. Having a section that tells the best way to link the library in a Boost test program would be nice. I could say more, but I would have to look over the docs more. Dave --- Outgoing mail is certified Virus Free. Checked by AVG anti-virus system (http://www.grisoft.com). Version: 6.0.701 / Virus Database: 458 - Release Date: 6/7/2004
Just wondering, what specifically couldn't you find in Boost.Test Docs?
A reference to the BOOST_XXX macros (like CHECK, CHECK_EQUAL, etc.). I finally realized you have to look at the headers, but that doesn't seem like it should be necessary.
http://www.boost.org/libs/test/doc/components/test_tools/reference/index.htm... And you definetly shouldn't look into headers.
Also, I couldn't find a reference for the command line arguments (log_level, etc.).
http://www.boost.org/libs/test/doc/components/unit_test_framework/parameters...
And how different fomat would help?
Having a section on the macros would help. Having a section on the command-line arguments would help. Having a section that tells the best way to link the library in a Boost test program would be nice.
http://www.boost.org/libs/test/doc/compilation.html and here http://www.boost.org/libs/test/doc/usage/generic.html#t3
I could say more, but I would have to look over the docs more.
Dave
HTH, Gennadiy.
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> wrote in message news:caebp9$nv5$1@sea.gmane.org...
[...]
http://www.boost.org/libs/test/doc/components/test_tools/reference/index.htm... It isn't obvious that this is where to look for this info. You have the "Test Tools" listed on the same level as the various "monitors". I'm not even sure why there is more than one kind of monitor, but it makes it difficult to navigate the docs.
And you definetly shouldn't look into headers.
Then what's this all about: http://www.boost.org/boost/test/test_tools.hpp
[...]
http://www.boost.org/libs/test/doc/components/unit_test_framework/parameters... Is there a way to get there from here: http://www.boost.org/libs/test/doc/components/unit_test_framework/index.html If so, I can't find it. At least not without perusing every last line of the docs. Is there a more obvious way to get to that page?
[...] http://www.boost.org/libs/test/doc/compilation.html and here http://www.boost.org/libs/test/doc/usage/generic.html#t3 [...]
These links say so little as to be unhelpful. For instance, if I chose to link to a library version of the Unit Test Framework for a test suite for a Boost library, what is the best way to do that? The name of the compiled library includes the Boost version number, so should that be hard-coded into the Jam file, or is there a way to make Jam aware of what version we're dealing with? Should Jam assume that this library is in the default installation location? These are the kinds of questions that seem like they would be fairly common to Boost library authors. Are other libraries just including the sources directly? Dave --- Outgoing mail is certified Virus Free. Checked by AVG anti-virus system (http://www.grisoft.com). Version: 6.0.701 / Virus Database: 458 - Release Date: 6/7/2004
"David B. Held" <dheld@codelogicconsulting.com> writes:
These links say so little as to be unhelpful. For instance, if I chose to link to a library version of the Unit Test Framework for a test suite for a Boost library, what is the best way to do that? The name of the compiled library includes the Boost version number, so should that be hard-coded into the Jam file, or is there a way to make Jam aware of what version we're dealing with? Should Jam assume that this library is in the default installation location? These are the kinds of questions that seem like they would be fairly common to Boost library authors. Are other libraries just including the sources directly?
Doesn't this explain a bit? http://www.boost.org/more/getting_started.html#Results -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
"David Abrahams" <dave@boost-consulting.com> wrote in message news:ufz8zsm8j.fsf@boost-consulting.com...
[...] Doesn't this explain a bit?
Well, it explains how the compiled libraries are named, which is exactly why I want to know the best way to link Boost.Test against a test program for another Boost library. Since the library name contains the version number of Boost, I want to know if the Jamfile that builds *my* test should hardwire that version number into the name it looks for the library or not. Not only that, but how do I make Jam automatically look under the corresponding platform? It doesn't seem like a good idea to write the Jamfile for just one platform, or create a separate file for every platform. Obviously, I haven't read up enough on Jam to know whether I can answer some of these questions myself. But some of them seem like they probably don't have obvious answers anyway. For instance, as a test writer, should I assume that the user who is building my test already built Boost.Test and installed it in the default location, or should I try to handle a case in which the user, say, installed the library in a system directory of some sort? I don't see answers to these questions in any of the references pointed to, but maybe I'm just not looking closely enough. Just to be concrete, let me give an example of what I mean: exe my_test : <lib>libboost_test-gcc-1_31.a my_test.cpp : <include>$(BOOST_ROOT) ; I'm pretty sure this is not the ideal way to write the Jamfile, but at first blush, it seems the most obvious way, pending better answers to my questions. I don't even know if that is the right syntax for linking to an external library or not. Dave --- Outgoing mail is certified Virus Free. Checked by AVG anti-virus system (http://www.grisoft.com). Version: 6.0.701 / Virus Database: 458 - Release Date: 6/7/2004
"David B. Held" <dheld@codelogicconsulting.com> writes:
"David Abrahams" <dave@boost-consulting.com> wrote in message news:ufz8zsm8j.fsf@boost-consulting.com...
[...] Doesn't this explain a bit?
Well, it explains how the compiled libraries are named, which is exactly why I want to know the best way to link Boost.Test against a test program for another Boost library. Since the library name contains the version number of Boost, I want to know if the Jamfile that builds *my* test should hardwire that version number into the name it looks for the library or not. Not only that, but how do I make Jam automatically look under the corresponding platform? It doesn't seem like a good idea to write the Jamfile for just one platform, or create a separate file for every platform. Obviously, I haven't read up enough on Jam to know whether I can answer some of these questions myself. But some of them seem like they probably don't have obvious answers anyway. For instance, as a test writer, should I assume that the user who is building my test already built Boost.Test and installed it in the default location, or should I try to handle a case in which the user, say, installed the library in a system directory of some sort? I don't see answers to these questions in any of the references pointed to, but maybe I'm just not looking closely enough.
Just to be concrete, let me give an example of what I mean:
exe my_test : <lib>libboost_test-gcc-1_31.a my_test.cpp : <include>$(BOOST_ROOT) ;
I'm pretty sure this is not the ideal way to write the Jamfile, but at first blush, it seems the most obvious way, pending better answers to my questions. I don't even know if that is the right syntax for linking to an external library or not.
Dave
Dave, I appreciate your problem, but I'm out of time to answer (trying to finish writing a book by tomorrow). Rene knows the answers and I'm hoping he'll follow up with you on this thread. Cheers, -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David B. Held wrote:
"David Abrahams" <dave@boost-consulting.com> wrote in message news:ufz8zsm8j.fsf@boost-consulting.com...
[...] Doesn't this explain a bit?
Well, it explains how the compiled libraries are named, which is exactly why I want to know the best way to link Boost.Test against a test program for another Boost library. Since the library name contains the version number of Boost, I want to know if the Jamfile that builds *my* test should hardwire that version number into the name it looks for the library or not.
Since you are talking about a Jamfile inside of the Boost tree, it should not have any version or platform or prefix reference in it. It should refer directly to the target in the Boost.Test library that you want to link to. The rest is determined automatically when the user builds the tests. Which in our case it means the regression test machines determine the build. -- See adjusted example below.
Not only that, but how do I make Jam automatically look under the corresponding platform? It doesn't seem like a good idea to write the Jamfile for just one platform, or create a separate file for every platform.
Definitely not a good idea ;-)
Obviously, I haven't read up enough on Jam to know whether I can answer some of these questions myself.
And assuming that the information was present in the first place. Which in this case it is but reading BBv1 docs is less than informative.
But some of them seem like they probably don't have obvious answers anyway. For instance, as a test writer, should I assume that the user who is building my test already built Boost.Test and installed it in the default location, or should I try to handle a case in which the user, say, installed the library in a system directory of some sort?
Since they are going to be running it from the library sources, they are going to be building from within the Boost tree and when built will automatically build the correct test library. Of course that breaks if you are planning on distributing outside of the Boost tree.
I don't see answers to these questions in any of the references pointed to, but maybe I'm just not looking closely enough.
It seems that there just are no simple to follow guidelines that answer those questions. And if I where to add some of that documentation, I'm not sure where it would go. There are at least 2 places where we describe regression test requirements/guidelines: http://boost.org/more/regression.html#Adding_new_test http://boost.org/more/test_policy.htm
Just to be concrete, let me give an example of what I mean:
exe my_test : <lib>libboost_test-gcc-1_31.a my_test.cpp : <include>$(BOOST_ROOT) ;
I'm pretty sure this is not the ideal way to write the Jamfile, but at first blush, it seems the most obvious way, pending better answers to my questions. I don't even know if that is the right syntax for linking to an external library or not.
OK, there are two ways of handling this depending on whether you are doing a test inside of the Boost tree or outside of it... When inside you can refer to the test library directly as such: exe my_test : <lib>../../../libs/test/build/boost_test_exec_monitor my_test.cpp <include>$(BOOST_ROOT) ; See boost-root/libs/format/test/Jamfile for such examples that also use the test system. Or if you are outside of the Boost tree, but still have access to the Boost distribution, you can use the project relative targets: * In your Jamrules add: project boost : $(BOOST_ROOT) ; * And then in the test do: exe my_test : <lib>@boost./libs/test/build/boost_test_exec_monitor my_test.cpp <include>$(BOOST_ROOT) ; See boost-root/libs/python/example for some uses of that. As you can see neither refers to versions or compiler. That is determined when the user builds and is filled in automatically. HTH. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com - 102708583/icq
Rene Rivera <grafik.list@redshift-software.com> writes:
Or if you are outside of the Boost tree, but still have access to the Boost distribution, you can use the project relative targets:
* In your Jamrules add:
project boost : $(BOOST_ROOT) ;
* And then in the test do:
exe my_test : <lib>@boost./libs/test/build/boost_test_exec_monitor ^ oops my_test.cpp <include>$(BOOST_ROOT) ;
You can use project relative targets from within boost too. I recommend it; it keeps things much cleaner. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
"Rene Rivera" <grafik.list@redshift-software.com> wrote in message news:40CC943C.4090609@redshift-software.com...
[...] exe my_test : <lib>@boost./libs/test/build/boost_test_exec_monitor my_test.cpp <include>$(BOOST_ROOT) ; [...]
Here's my Jamrules (which I assume can be in the same directory as my Jamfile and tests?): project boost : $(BOOST_ROOT) ; And here's my Jamfile: subproject libs/policy_ptr/test ; exe smart_ptr_test : <lib>@boost./libs/test/build/boost_unit_test_framework smart_ptr_test.cpp <include>$(BOOST_ROOT) ; Now, I have boost installed under /usr/local/boost, and the sandbox in /usr/local/boost-sandbox. I have BOOST_ROOT set to /usr/local/boost. When I do "bjam", I get: /usr/local/boost-sandbox/../boost/tools/build/v1/allyourbase.jam:1280: in enter- subproject *** argument error * rule split-path ( path ) * called with: ( ) * missing argument path /usr/local/boost-sandbox/../boost/tools/build/v1/allyourbase.jam:1581:see defini tion of rule 'split-path' being called /usr/local/boost-sandbox/../boost/tools/build/v1/boost-base.jam:1506: in depende nt-include /usr/local/boost-sandbox/../boost/tools/build/v1/boost-base.jam:2005: in main-ta rget /usr/local/boost-sandbox/../boost/tools/build/v1/boost-base.jam:1349: in declare -local-target /usr/local/boost-sandbox/../boost/tools/build/v1/boost-base.jam:2024: in exe Jamfile:5: in load-jamfiles /usr/local/boost-sandbox/../boost/tools/build/v1/bootstrap.jam:22: in boost-buil d /usr/local/boost-sandbox/boost-build.jam:7: in module scope Any idea what to do next? Also, I put the <include> line after a colon originally, but your example does not have that. What is the difference, and why? Dave --- Outgoing mail is certified Virus Free. Checked by AVG anti-virus system (http://www.grisoft.com). Version: 6.0.701 / Virus Database: 458 - Release Date: 6/7/2004
"David B. Held" <dheld@codelogicconsulting.com> writes:
Any idea what to do next? Also, I put the <include> line after a colon originally, but your example does not have that. What is the difference, and why?
Get rid of the .
exe smart_ptr_test : <lib>@boost./libs/test/build/boost_unit_test_framework ^------ here smart_ptr_test.cpp <include>$(BOOST_ROOT) ;
-- Dave Abrahams Boost Consulting http://www.boost-consulting.com
"David Abrahams" <dave@boost-consulting.com> wrote in message news:uhdt9bzhj.fsf@boost-consulting.com...
"David B. Held" <dheld@codelogicconsulting.com> writes:
Any idea what to do next? Also, I put the <include> line after a colon originally, but your example does not have that. What is the difference, and why?
Get rid of the . [...]
I tried that before and tried it again now, and it has no effect. It appears to be finding the path ok, so it seems that I have some other problem. Dave --- Outgoing mail is certified Virus Free. Checked by AVG anti-virus system (http://www.grisoft.com). Version: 6.0.701 / Virus Database: 458 - Release Date: 6/7/2004
"David B. Held" <dheld@codelogicconsulting.com> writes:
"Rene Rivera" <grafik.list@redshift-software.com> wrote in message news:40CC943C.4090609@redshift-software.com...
[...] exe my_test : <lib>@boost./libs/test/build/boost_test_exec_monitor my_test.cpp <include>$(BOOST_ROOT) ; [...]
Here's my Jamrules (which I assume can be in the same directory as my Jamfile and tests?):
Your Jamrules must be in your project's root directory
project boost : $(BOOST_ROOT) ;
And here's my Jamfile:
subproject libs/policy_ptr/test ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This says the Jamfile is 3 levels down in your project's directory hierarchy. You gotta decide which you're trying to do.
;
exe smart_ptr_test : <lib>@boost./libs/test/build/boost_unit_test_framework smart_ptr_test.cpp <include>$(BOOST_ROOT) ;
Now, I have boost installed under /usr/local/boost, and the sandbox in /usr/local/boost-sandbox. I have BOOST_ROOT set to /usr/local/boost. When I do "bjam", I get:
If you're developing in the sandbox, just follow the model of sandbox/libs/move/test/Jamfile. You don't want a Jamrules; the sandbox already has one. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
http://www.boost.org/libs/test/doc/components/test_tools/reference/index.htm...
It isn't obvious that this is where to look for this info.
You asked for Test Tool reference: where did you expect it to be?
You have the "Test Tools" listed on the same level as the various "monitors".
Because it's one of the components of the Boost.Test library.
I'm not even sure why there is more than one kind of monitor, but it makes it difficult to navigate the docs.
This is covered here: http://www.boost.org/libs/test/doc/components/index.html
And you definetly shouldn't look into headers.
Then what's this all about:
This is header, which you should NOT use to be able to use Test Tools
[...]
http://www.boost.org/libs/test/doc/components/unit_test_framework/parameters...
Is there a way to get there from here:
http://www.boost.org/libs/test/doc/components/unit_test_framework/index.html Yes. See configuration link.
If so, I can't find it. At least not without perusing every last line of the docs. Is there a more obvious way to get to that page?
Like what?
[...] http://www.boost.org/libs/test/doc/compilation.html and here http://www.boost.org/libs/test/doc/usage/generic.html#t3 [...]
These links say so little as to be unhelpful.
It says everything you need to know to be able to build Boos.Test library, given you know how to use Boost.Build or any other build system.
For instance, if I chose to link to a library version of the Unit Test Framework for a test suite for a Boost library, what is the best way to do that?
I donno. Add to your makefile, project, solution e.t.c.
The name of the compiled library includes the Boost version number, so should that be hard-coded into the Jam file, or is there a way to make Jam aware of what version we're dealing with?
I personally never use library files with versions incorporated.
Should Jam assume that this library is in the default installation location?
All above questions has no place in Boost.Test docs, since have have nothing to do with Boost.Test build (in general) IMO.
These are the kinds of questions that seem like they would be fairly common to Boost library authors. Are other libraries just including the sources directly?
None. As far as I know.
Dave
Gennadiy.
On 06/13/2004 04:19 AM, David B. Held wrote: [snip]
These are the kinds of questions that seem like they would be fairly common to Boost library authors. Are other libraries just including the sources directly?
Dave
Dave, I can sympathize with you. I took your earlier policy_ptr tests with the makefile and created a Jamfile.v2; however, after trying to compiler from a separate source tree without success (IIRC), I moved the sources to a subdirectory of boost: boost-root.ln/development/libs/managed_ptr/test this worked with the following Jamfile.v2 in the test directory: <------------------- import testing ; project manged_ptr_test : requirements <hardcode-dll-paths>true : default-build debug ; { test-suite "managed_ptr" : [ run own_rent_ptr.cpp ../../io/filters/src/mout.cpp ../../../../libs/test/build//boost_unit_test_framework ] ; }
-------------------- and with the following Jamfile.v2 in the development directory: <-------------------- project boost : requirements <toolset>gcc <include>. : usage-requirements <include>. ; -------------------- and with the following Jamfile.v2 in boost-root.ln: <-------------------- # # This is Boost Jamfile for Boost.Build V2. # Currently, known to work on Linux with gcc # # To build Boost with it, run # # bjam --v2 link=static # # from the top-level directory
project boost : requirements <include>. : usage-requirements <include>. : build-dir ./build_dir ; build-project libs/test/build ; build-project libs/date_time/build ; build-project libs/regex/build ; build-project libs/signals/build ; build-project libs/graph/build ; # Comment this out if you don't have Python2.2 installed build-project libs/python/build ; build-project libs/thread/build ; build-project libs/filesystem/build ;
-------------------- I think the only change I made to the toplevel Jamfile.v2 from what came with the download from boost was the build-dir specification.
Anyway, here's the output: <-------------------- cd /home/evansl/prog_dev/boost-root.ln/development/libs/managed_ptr/test/ bjam --v2 XXX ...patience... ...found 410 targets... ...updating 4 targets... gcc.compile.c++ ../../../../build_dir/development/libs/managed_ptr/test/own_rent_ptr.test/gcc/debug/own_rent_ptr.o gcc.link ../../../../build_dir/development/libs/managed_ptr/test/own_rent_ptr.test/gcc/debug/own_rent_ptr testing.capture-output ../../../../build_dir/development/libs/managed_ptr/test/own_rent_ptr.test/gcc/debug/own_rent_ptr.run **passed** ../../../../build_dir/development/libs/managed_ptr/test/own_rent_ptr.test/gcc/debug/own_rent_ptr.test ...updated 4 targets... Compilation finished at Sun Jun 13 14:25:52
------------------
HTH.
"David B. Held" <dheld@codelogicconsulting.com> wrote in message news:caeaih$m8f$1@sea.gmane.org... | "Gennadiy Rozental" <gennadiy.rozental@thomson.com> wrote in message | news:cacotf$cl5$1@sea.gmane.org... | > [...] | > Just wondering, what specifically couldn't you find in Boost.Test | > Docs? | | A reference to the BOOST_XXX macros (like CHECK, | CHECK_EQUAL, etc.). I finally realized you have to look at the | headers, but that doesn't seem like it should be necessary. | Also, I couldn't find a reference for the command line arguments | (log_level, etc.). FWIW, I too had some problems trying to find BOOST_XX macro documentation and which headers to include. I browsed several examples, but coulnd't figure out what to include so I ended looking into test directories for various projects. I think a single link on the main page called "Headers" would help. At the end of the link should be a table with all library headers and what they include. The table could also provide additional links into the documentation for each item mentioned. br Thorsten
FWIW, I too had some problems trying to find BOOST_XX macro documentation and which headers to include. I browsed several examples, but coulnd't figure out what to include so I ended looking into test directories for various projects.
Did you read Test Tools docs here: http://www.boost.org/libs/test/doc/components/test_tools/index.html Is there something missing?
I think a single link on the main page called "Headers" would help. At the end of the link should be a table with all library headers and what > they include. The table could also provide additional links into the documentation for each item mentioned.
I intentionally does not provide top level Headers link. I prefer users to learn library from tutorial prospective and does not go into details where is what implemented. Tset Tools doc says what headers you need to include to be able to use them. Do you think it should be made clearer?
br
Thorsten
Gennadiy.
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> wrote in message news:cai6b3$6rf$1@sea.gmane.org... | > FWIW, I too had some problems trying to find BOOST_XX macro documentation | and which headers to include. I browsed several | > examples, but coulnd't figure out what to include so I ended looking into | test directories for various projects. | | Did you read Test Tools docs here: | http://www.boost.org/libs/test/doc/components/test_tools/index.html yes, I remember browsing the docs quite some time. But I think my problems were most when starting out at http://www.boost.org/libs/test/doc/index.html I had little idea about getting to that specific page. | Is there something missing? | | > I think a single link on the main | > page called "Headers" would help. At the end of the link should be a table | with all library headers and what > they include. The table could also | provide additional links into the documentation for each item mentioned. | | I intentionally does not provide top level Headers link. I prefer users to | learn library from tutorial prospective and does not go into details where | is what implemented. Tset Tools doc says what headers you need to include to | be able to use them. Do you think it should be made clearer? Hmm..it's always hard to say. But I think your documentation might be too thorough :-) I mean, from the start page I have so many choises, that I don't know what is tutorial and what is reference. This page http://www.boost.org/libs/test/doc/components/test_tools/index.html is probably the one we all need to go into first. Maybe you should consider to rename it "getting started"? br Thorsten
At Friday 2004-06-11 02:15, you wrote:
Ok, if the Boost style documentation is too simple, and docs like Spirit are too cute, what is a nice, happy median? If we're going to demand uniformity in licensing, should we also demand more uniformity in documentation? I think a single documentation style across Boost would make it even easier to learn new libraries. I recently found it very difficult to find the information I wanted about the Boost.Test library, as well as Boost.Preprocessor. What can be done about these issues?
Dave
A "single style" for the documentation may be out of reach. I _still_ haven't figured out the concept check "system" and I find that documentation particularly inscrutable. Many years ago my father wrote me a letter about "volunteer organizations".. I'd just been elected president of an astronomy club (he was an officer of a square-dance club). What he had to say applied then, and I think here. In any such organization (and to a large extent this includes such ad hoc groups as "people using C++, boost in particular") you have the beginners (we call them newbies) and those who are attempting to "run" the organization (those who have been around for a while, and are willing to expend the effort to "make it better"). Unfortunately, this produces a conflict which can destroy the organization: the newbies want to learn "basic" stuff, the old timers (some call us the old farts) want to explore the edges and nooks and crannies and do, sometimes, very complex stuff. The same applies, IMO, to documentation. The audience is (or, if you prefer, the audiences are) very like a club. There are those who are just starting and need to learn some fundamentals (and they enjoy them). There are others who have been around the block (sometimes the planet) and need details that only a language lawyer can love (see the ISO standard for C++ for an example of the latter). Writing a single document which can serve both groups is challenge enough, but we have yet a third (and maybe fourth, fifth or...) group(s). One that leaps to mind immediately is the person that "just needs to know ....blah". They want the document to be random access and contain _all_ the relevant information at the spot _they_ choose to look. This requires that the author(s) be prescient enough to group the information in exactly the same manner as the presumed reader (unlikely doesn't begin to express the probability of _that_ happening). Yet another difficulty is in getting people to actually READ the documentation. I'm one of those weird guys that actually will read the documents/book/whathaveyou cover to cover (I'm not sure what that means w/ respect to the Spirit docs (they weren't as linear as I would have preferred)...but I read all of what I could find at the time). Hyperlinks (yes, they're useful...immensely so) exacerbate the problem. It's far too easy to get sidetracked. The reason I try to read books front to back (then Langer & Kreft come along and say "read section 2 unless you're pretty sure you've got most of it" then continue here) is because the author _generally_ has a reasonably good idea of what order to present the information. This is particularly important in such as our genre since so much of what comes later _depends_ on other things (hopefully presented earlier). Sometimes even a good author (Scott Meyers leaps to mind) discovers that he needs to refer (with a link on the CD) to items which come later in the book. What are mere mortals to do? A fine example of documentation is Nicolai's tome "The C++ STandard Library ... A Tutorial and Reference". Right on the front cover we see that there are (at least) two distinct use(r)s for this document. In facing a monumental task, Nicolai does more than an admirable job, yet he writes 799 pages (my edition) and covers _only_ (well primarily) the STL. His book is the most worn of all my C++ books, and is the only book I rate "a must have" on my recommended reading list. to wit: I recommend the following books: read them in mostly the order listed "Accelerated C++" Andrew Koenig & Barbara Moo "The C++ Standard Library" Nicolai Josuttis --- a "must have" "Effective C++", "More Effective C++", "Effective STL" Scott Meyers "Exceptional C++", "More Exceptional C++" Herb Sutter "The C++ Programming Language" 3rd edition or later Bjarne Stroustrup "Modern C++ Design" Andrei Alexandrescu "C++ Templates" Vandevoorde & Josuttis "Standard C++ IOStreams and Locales" Langer & Kreft Do not infer that I think that the STL is small, but in comparison to the boost libraries, it is. So where does that leave us (boosters)? Difficult to say. I've read the only (to my knowledge) actual _book_ about any portion of boost: the graph library and although I'm sure it's a very good book, my understanding of how to use the library still suffers. Jeremy, don't take offense, the problem is mine, I knew _nothing_ about formal graph theory when I got the book, now I know something, but not WHERE to use the library, or WHY. The book is exceptionally detailed, and likely quite good to someone who already knows graph theory. This is a fine example (from what I can tell) of documentation for "the old guys", for a newbie (in this case me) it's difficult at best. Do we need tutorials for any? some?? all??? of the libraries in boost? clearly yes for any, but likely no for all (perhaps we should use the tribool for answer here). Do we need reference documents? you betcha!! At least two kinds...one for people USING the library, another for people who will need to extend or fix the library (users _may_ not need to know the implementation details, maintenance folks will). Scott Meyers says there are two audiences for every program... I believe that includes the documentation for every program. Raison d'être for some libraries? very likely. How about some background for the problem domain? I'd like one for concept-check and boost graph. This almost leads to a conclusion that something like wikipedia or planetmath will be necessary to gather all the information, since the task appears more than one _volunteer_ author could do....even for a single library in the collection. How we present it in tutorial form, I do not know. A large problem with writing documentation post "post facto" is that the author(s) have spent _so_ much time completely immersed in the project and concepts that some very fundamental things can get left out. Parts of the project have become so ingrained that the author(s) almost cannot conceive of "the axioms" being unknown to all. Most of my above comments come from spending time (too much, likely) hanging out on IRC (Undernet #C++ channel) and attempting to help mostly newbies and _some_ (very few) very advanced people use the language (and boost). I've also been programming professionally for 39 years and have written a fair number of documents on the programs I've written (I don't write nearly as well as _any_ of the authors of the books I recommended above). I've also seen my share of poor to downright lousy documentation on programs that I've tried to use and or fix. I believe it's important to have good documentation. I've been pleased (mostly) with the documentation for stuff in boost (I don't even know for sure _all_ of what's in there any more). Does it need "fixing"? Well... I'd say the stuff _I_ can't understand certainly does, but we'll get different people saying different things are inscrutable. And authors of those sections (correctly) stating that we newbies just don't have the background to appreciate the documentation. With no pointers to _where_ such documentation exists, as far as we're concerned, the library might as well not exist. I'll be glad to lend assistance to any updates, though my proofreading skills seem to be far better than my writing skills. Victor A. Wagner Jr. http://rudbek.com The five most dangerous words in the English language: "There oughta be a law"
Victor A. Wagner Jr. wrote:
At Friday 2004-06-11 02:15, you wrote: I recommend the following books: read them in mostly the order listed "Accelerated C++" Andrew Koenig & Barbara Moo "The C++ Standard Library" Nicolai Josuttis --- a "must have" "Effective C++", "More Effective C++", "Effective STL" Scott Meyers "Exceptional C++", "More Exceptional C++" Herb Sutter "The C++ Programming Language" 3rd edition or later Bjarne Stroustrup "Modern C++ Design" Andrei Alexandrescu "C++ Templates" Vandevoorde & Josuttis "Standard C++ IOStreams and Locales" Langer & Kreft
Matt Austern's book "Generic Programming and the STL" is magnificent and, for me, the model of how programming books should always be written. Nothing is explained in his book before it is necessary and there is never a reference to something which occurs later in the book and hasn't already been discussed to some extent at least at a general level of understanding. The care which he took to organize the book so that it is completely understandable about a difficult subject shows on nearly every page. Good writing on computer programming is largely a problem of good organization when the writer is knowledgable in their subject matter. It is a difficult task and, unfortunately, there are few technical writers who can do it really well. Besides Mr. Austern's splendid effort, the only other technical writer I have ever read who consistently writes books at that sort of organizational level is Jeff Richter, who writes about Windows programming topics. Of course all of the writers you mention have deep knowledge of C++, but not all of them have the ability to organize their writing as well as it could be. But of the ones I have read on your list, all put out the effort to organize their knowledge as best as they could. That to me is very important.
Do we need reference documents? you betcha!! At least two kinds...one for people USING the library, another for people who will need to extend or fix the library (users _may_ not need to know the implementation details, maintenance folks will). Scott Meyers says there are two audiences for every program... I believe that includes the documentation for every program.
I would like to second your comment that their are usually two distinct audiences. A person first learning an implementation and one who is pretty good at it and who just needs to understand some of its nooks and crannies. Most of the Boost documentation is excellent, and serves the purposes of both. I am especially thinking of Mr. Gregor's documentation which addresses different audiences by having sections labelled for the level of person who is first approaching his implementations. Some of it is just bewildering to the person first trying to learn the subject at hand, even given a decent background in the area. I know the suggestion for the latter is often to spend time digging things out and then trying things out to see what the result is, but there are people like me who no matter how many things I can discover experimenting with code, still feels lost if I do not have a clear understanding of the ideas and concepts behind what I am doing.
How we present it in tutorial form, I do not know. A large problem with writing documentation post "post facto" is that the author(s) have spent _so_ much time completely immersed in the project and concepts that some very fundamental things can get left out. Parts of the project have become so ingrained that the author(s) almost cannot conceive of "the axioms" being unknown to all.
You have "hit the nail on the head" so to speak. It is easy to know something intimately, if one is the creator, and not realize that others do not have an understanding which the creator does. OTOH I understand the creator's reticence to slow down and explain things from a newbie's point of view. Unfortunately that reticence has often led to some great programming concepts going by the wayside because an audience finds it just too difficul t to understand and therefore use.
I believe it's important to have good documentation.
Bravo ! It is good to know there is someone else out there who believes that. I will go even farther. I think good documentation in the programming world is just as important as good implementation.
I'll be glad to lend assistance to any updates, though my proofreading skills seem to be far better than my writing skills.
My writing and proofreading skills are both pretty good. I will also be glad to lend assistance to anyone who asks me if I can help improve their Boost documentation as long as I can understand what they are doing. I won't write someone else's documentation for them in the sense that they don't feel that they have time to work on it themselves, which is something I can nevertheless personally understand as my own time, like most everyone else's, is limited by the needs to work and make a living.
participants (8)
-
David Abrahams -
David B. Held -
Edward Diener -
Gennadiy Rozental -
Larry Evans -
Rene Rivera -
Thorsten Ottosen -
Victor A. Wagner Jr.