At 04:46 PM 7/25/2002, David Abrahams wrote:
However, enough people have had problems approaching this library that I thought it would be useful to ask about what would make a gentle introductory example. Beman recently sent me the enclosed, but it seems to define such an oddball toy iterator that I'm not sure it would be a very good motivating example.
ia_experiment.cpp is definitely oddball and definitely a toy. It was written to help me understand why I was getting compile errors from a real adaptor. Someone else can probably come up with an introductory example which is less oddball. But I'd like to defend the general principle of "toy" introductory examples. When someone knows nothing about a topic, a toy example is the best introduction. It is "known good", and can be used to verify that compilations using the library work as expected. It can be modified to see the effect of changes. Because it is a toy, it is totally non-threatening. It makes the reader feel superior, rather than like a dunce. The "C Programming Language" and "C++ Programming Language" books both started with a little "hello, world" program, very much a toy. Although simple, it starts the ball rolling with something that works and is understandable almost every reader. In the case of ia_experiment.cpp, it illustrates the relationship between the finished iterator, the Base class, and the Policies class with greater clarity IMO than documentation in any form other than C++ code. --Beman