Re: Doxygen - another sample, preliminary comments

[Benjamin Kosnik <bkoz at redhat dot com>]

> Sounds about right.  I'm not sure whether or not the documentation
> generation should be on by default.  I think those people that will
> most require documentation are also those who don't understand the
> configure & build process too well, so perhaps --enable-doxygen is the
> more appropriate default.  Experienced users can always turn it off if
> they have a local copy already, or for whatever reason.

I'm a bit concerned with the recent evolution of the docs subdir.

It's my strong preference to have a docs directory with all the HTML and
.texi files included in the distribution by default. For whatever reason,
it looks like a copy of the HTML files will be living outside the main
source tree. This is ok, but I really want to have active HTML
documentation within the source directory.

My reasoning for that is as follows: I know that I actually check in
patches to the documentation when I change things. A good example of this
is the configopts.hml page and configure hackery: 

2000-11-01  Benjamin Kosnik  <bkoz@purist.soma.redhat.com>

	* bits/basic_file.h (_M_open_mode): Change signature, move
	specializations to..
	* config/c_io_libio.cc: ...here.
	* acinclude.m4 (GLIBCPP_ENABLE_CSTDIO): Add sdtio option, remove wince.
	* aclocal.m4: Regenerate.
	* configure: Regenerate.
	* config/c_io_stdio.h: New file.
	* config/c_io_stdio.cc: New file.
	* docs/configopts.html: Modify documentation.

I'd like to see this trend continue. 

This preference is born out of g++'s nearly-always out of date configure
options documentation. I'd prefer the library not take this same approach,
and consider the current libstdc++-v3 arrangement superior.

So, I'm now against the removal of the docs/* content.

Continuing in this ranting mode, I'd also like to see the doxygen bits
live inside a docs subdir, and not necessarily a configure-time
option. I'd rather see a special makefile rule to build the enhanced
documentation than a configure time option. Let's face it: re-configuring
for documentation, even 'enhanced documentation'  is a complete nightmare.

People who then want the enhanced documentation can build
it: people who don't care don't have to waste cycles generating it. 


I'd rather see subdirectories created in the docs directory, than the
profileration of top-level documentation directories. For instance

docs/html
docs/doxygen
docs/texi

or whatever.

-benjamin