My comments below...

Alessio


 > There are a couple of projects in use at Apache: Forrest and Maven.
 > I haven't used either but I believe a lot of the Web pages around
 > here are generated by Forrest.

Maven is a PM tool that takes care of automating the build process and the 
project description, but the first goal is met by building upon Ant... and so it 
is mostly Java-oriented; as far as the second goal, Forrest is a better fit.


 > Going the Doxygen route is definitely very appealing for new code,
 > but converting the existing sources would be a huge amount of work.

Yes, I'm trying to plan for std::tr1 too.
Probably the existing reference guide can be maintained as it is (in HTML) and 
slowly migrated to Doxygen in case we decide to go for it; the decision can be 
taken based on the results of a prototype.
I will be unavailable this month but can certainly spend the first week of 
October creating the prototype for a subset of the classes/functions of the doc 
(maybe Marc can point me to the subset that makes more sense, which has to 
include tables, lists, ...).

 > The stdlib reference, as you know, is large. A cut and paste
 > approach has a number of factors that would make it both tedious and time
 > intensive:
 > care in accurately matching each description with its method signature;

ok

 > chopping the continuous lines of the current documentation into
 > 80 character line lengths for insertion into the code;

Emacs does it for you

 > adding doxygen
 > comment tagging to each description.

this is the real work

 > Then, too, there is the issue of
 > conditional compilation, which doxygen can deal with, but the technique for
 > doing that is a bit complex.

doxygen lets you specify a set of header files with all the macros that you 
would like to be defined (let's call this set the "bootstrap macro subset")
doxygen will then take that into account when preprocessing the code.

 > We do not really deal with conditional
 > compilation in our current documentation, but I think we will have to with
 > doxygen because it preprocesses the code before extracting the
 > documentation. (Actually, you can disable preprocessing, but I am guessing
 > that would create more problems than it would avoid.)

we have then several options:
- generate specific documentation for each supported compiler (that is, for each 
supported bootstrap macro subset)
- create a documentation-specific bootstrap macro subset
- anything in between the above


 > Maybe Alessio has some automation solutions in mind that would reduce the
 > time. I can think of a few possibilities, but I am uncertain how truly
 > effective they would be. It might be that the effort to get the automation
 > working well would exceed the time ultimately saved.

we can have a clear idea about that after the prototype has been built
I hope October will be timely enough for the project deadlines (BTW, which are 
the deadlines?)