toward unified, structured documentation

["Benjamin Kosnik" <bkoz at redhat dot com>]

Often I bemoan the shoddy state of libstdc++ documentation. It feels
often like a lumpen, out-of-date mess. Today (ahem, two weeks ago) I
tried to look at it objectively, and upon closer examination, I see
that I was incorrect on some things. Somewhat mistaken, somewhat
surprised.

Quick: how many separate documentation sub-projects currently exist?
Two? Four? More?

It turns out, six.

- html index
- doxygen modules, which track the SGI STL docs
- faq index
- porting
- porting-howto.html
- text files originally written by Nathan

Ooops. I missed one:

- pb_ds performance testing docs

Perhaps I missed one or two others. It is no wonder that there is so
much confusion and that creating documentation is such a chore, and
that everybody who adds docs does it differently.

I plan on unifying this into something coherent, and more structured
along the lines of a proper manual.  For a GNU project, this usually
means something like texinfo and docbook. Things that are off the
table: writing our own freaking documentation tool.

Steps to unify:

0) create central index/table of contents based on all existing content.
See glibc manual, others. This is currently complete, modulo FAQ items.

1) Index merge FAQ. By merge, I mean fit into a unified index and
update for current information. If the note is no longer relevant,
discard. The goal should be to have all FAQ items point in to the
larger index, with the items immediately surrounding the FAQ entry
related to the content.

2) Investigate index merge links to doxygen modules linkage

3) Convert unified index into something via magic step, docbook-y
This could take the libc approach of multiple texi files.

4) Edit, add remaining bits, update.

>From this, some mysterious miracle writer will go through and flesh
out bits in the future. I'd hoped to get to that too, but if this is
the true state of things, perhaps it was too optimistic. For certain,
locales and io need serious documentation love. I believe there are
several bugzilla's about this...

Unknowns

1) renee rivera / doug gregor work on boost book with doxygen xml output
2) doxygen output cleanup: css work??
3) docbook tools
4) accuracy/completion/status of the doxygen SGI STL work
5) gcc FAQ or wiki: how integrated into gcc? See also Diegos posts
RFC: Creating a live, all-encompassing architectural document for GCC
http://gcc.gnu.org/ml/gcc/2007-10/msg00511.html
6) hoverhelp for Eclipse CDT. We should have hoverhelp for libstdc++ types.
This should probably be derived from our man pages...
7) man pages

I am scheduled to work on completing up to stage 3 in January 2008. Of
course, if the FSF wants to hire an editor to help me (as they did for
Roland and the glibc manual), I'd be delighted.

I do intend to update the backwards compat bits with the changes for
4.3 as my first task this week, after investigating the various
Bugzillas that have been filed about this work. (Sorry about the delay
on these y'all.)

Special thanks to Roland for encouraging me in this quest, and for
Tromey's gentle-but-motivating sighing when he tries to read the
doxygen docs next to me...

-benjamin