As far as I see, we can only push the categorized reference sections (phpdoc/RFC/manual.xml.in) forward, if we do handle the matter in livedocs. Since there are no people who would like to volunteer to implement the enhanced TOC stuff in DSSSL (online and downloadable versions) and XSLT (extended CHM) I know of, we should keep the current manual.xml.in file for these versions, and move the RFC/manual.xml.in file to something like phpdoc/php-manual.xml.in (or some other shiny name, which is future compatible :) This new file would be used by livedocs, and the old file would be used by the DSSSL and XSLT builds. Both files would need to be updated, when new extension docs, etc. are added (until DSSSL and XSLT rendering stuff gets completely abandoned).
I'd rather rename the "old" one to manual.xml.old.in and fix the buildscripts and use the new one as "manual.xml.in".
Well, we are not tied to naming it manual.xml.in, it could be book.xml.in or usermanual.xml.in or anything :) I expect tools and outside sources (IDE supplied scripts generating quickreferences, Zend manual generation, etc) to break if we replace the original manual file, whith something which is not DocBook.
If this is fine, then the tagging should be decided on. Seems like we need to modify docbook anyway we choose, since there is no option we can choose to not modify docbook and introduce some section levels there. Hartmut's proposal does not fit the multilevel sections proposed in the RFC, this is why I suggested using <section> tags. This might however have some meaning in livedocs, so since we need to modify docbook anyway, we can identically choose to introduce a new tag, like <refgroup> or something like this.
The idea of livedocs was that it also works for any other DocBook XML source, so that should not be changed (I use it for such things).
This is another point on the side of adding a new tag, since for other DocBook XML documents, that extra tag handler would not be a problem. However if we overload a tag, and provide it special meaning in our environment, then it would be problematic for general usage. There is no possibilty in stock DocBook we have found so far to provide a multilevel (or even a single level) toc above the reference section.
Goba
