[v3] doc/html conversion to doc/xml

[Benjamin Kosnik <bkoz at redhat dot com>]

This is a documentation-only patch that transforms the current
libstdc++ documentation into a coherent (hopefully) set of books
structured in the DocBook 4.5 style. This approach is modeled on a
similar approach taken by valgrind, whereby the manual, FAQ, and other
guides are all books in a larger documentation "set." The actual
organization strives to be similar to the current HTML index, but
expanded and with coherent navigation. The content and layout should
surprise none paying attention to mainline.

I believe this meets the FSF/savanna.gnu.org documentation request for
a libstdc++ manual:
https://savannah.gnu.org/people/viewjob.php?group_id=3972&job_id=267

At least the initial parts. I seem to have limited ability WRT
adding or editing items on savannah. Is this site officially dead? Or
just not actively administered?

Anyway.

This conversion is near-complete. Remaining is ext/pb_ds, which will
remain unfinished at the moment. The rest is considered complete, and
certainly a passable first draft. 

So, the way docs will work from now on:

1) libstdc++/doc/html is frozen, forever
2) All but libstdc++/doc/html/ext/pb_ds should be deleted, and
replaced with the generated html files
3) All future documentation work should use the doc/xml/* files.

To build the current documentation:

1) cd build/libstdc++
2) type in
   make doc-html
   make doc-pdf
   make doc-xml-validate

These build the html or pdf versions of the docs, and the last
validates the documentation structure against the DocBook DTD. 

Here is current output:
http://people.redhat.com/bkoz/documentation
http://people.redhat.com/bkoz/documentation/html.20080210/set-index.html

Some additional tools may be necessary, depending on the host and the
desired format.

This completes my near-term work on the documentation, up through stage
3 here:
http://gcc.gnu.org/ml/libstdc++/2007-11/msg00018.html

I claim victory.... special thanks to Daniel Veillard for helping me
with XML validation concepts and understanding xmllint output.

Future work: 

Getting FSF to do this:
https://savannah.gnu.org/support/?106094

Getting the FSF or other party to clean up the markup, write missing
pieces. Hopefully this will seem like less of an impossible task now.

Cleanup of internal linking. Before we had no way to do intra-document
links, so there are a lot of URL references that should instead be
intra-document links. 

Figure out how to do a proper index for PDF. As pdf is a
stretch goal, I let this slide. I did see some commentary from the
subversion doc writers on how to do this.

Markup for PDF output.

More consistent markup.

Linkage to doxygen output. This seems more possible now.

best,
benjamin

Attachment: p.20080210.bz2
Description: application/bzip