"David Abrahams" <dave@boost-consulting.com> wrote in message news:<umzh4zoq6.fsf@boost-consulting.com>...

For what it's worth, I feel a little uneasy about the links myself.

That said, I feel uneasy when I scrutinize any link style too closely

Has any thought been put into using Doxygen to document both source-code and to create a web based help document? For those who are not familiar with Doxygen, Doxygen is a free program that uses tags in your source code to create a help document. The help document can be HTML, Man-Pages, RTF, XML, and Windows Help. See following link: http://www.stack.nl/~dimitri/doxygen/index.htmlfrom I'm currently documenting smart_ptr, and I'm using the Doxygen tags to do so. Check out the following link: http://axter.com/smart_ptr/ The above link and has been created automatically using the following source code: http://code.axter.com/smart_ptr.h I've only recently started the document, so only a few of the policy classes have documentation, like the following: http://axter.com/smart%5Fptr/structallocator__default__policy.html But this gives you an example of what Doxygen can do. In the above link, you'll see some example usage code. That example code is not inside the header, and instead, it's pulled from a source file using the following tags: <b>Example Usage</b> @include ../examples/example_allocator_policy_usage.cxx The example_allocator_policy_usage.cxx file is a file that is part of my unit test project. This insures that the code at least is compliable. How often have you pull some example code, to find out it doesn't compile, let alone work. I think this would be a good standard to push for boost. I wouldn't mind volunteering to document some of the other boost classes using the above method.