Hi! Well, I spent some time with investigating what structures can we use to achive the groupings we already discussed. The most important priority was that no change should be required to any other file but manual.xml.in, or a very small number of changes should be required.
So we needed a structural element that we can use to group up <reference> parts and these structural elements should fit into a <part> (which is the main division in our manual). Here is the content model of <part>: part ::= (beginpage?,partinfo?, (title,subtitle?,titleabbrev?), partintro?, (appendix|chapter|toc|lot|index|glossary|bibliography|article| preface|refentry|reference)+) Now we put <reference> tags straight into the <part>, so this is OK. But there is no structural element here we can use to group up references, as <chapter> (which would be the only sensible grouping element here) cannot include <reference>... What can include reference? The possible partent of reference are book and part. That's all. So as the current DocBook TDG shows, we have no way to group references in DocBook 4.1.2. That lead me to think about extending or at least modifying docbook for us to be able to gruop references. For this reason, I have introduced "new DTD" in phpdoc/dtds named phpbook.dtd. This needs to have a non-docbook DTD, as it's not DocBook (see the TDG for more info). What I needed was to add section to the content model of <part>, and add <reference> as a possible child of <section>. This is all done in phpbook.dtd. The manual.xml.in file now in phpdoc/RFC uses this dtd to be able to group reference sections. It works quite well, it generates all the HTML pages. The only problem left is that for some reason the <reference> titles are not printed in <section>s. This is a DSSSL style sheet issue, so it should be adjusted... The question is if you agree on using this phpbook DTD "instead of" DocBook, as AFAIK this is the only DTD enables us to correctly group references. There were some discussions here on the list about creating a somewhat customized DocBook DTD (because of see also lists), and it ended up in the conclusion that it is not needed, as we can use <note role="seealso"> instead (which maybe was not the best solution, but at least it works with the current DocBook DTD). Now as it seems, we have no other way to group <reference>s, then to introduce a simple customization of DocBook. And if we go on this way, maybe some other simplifications can be introduced in the future, like <iniopt>extension_dir</iniopt> linking to the options documentation, etc. I am crossposting this to php-gtk-doc, because they also use a modified version of DocBook, and they have no problem with it, so maybe they can add us some positive impressions about DocBook modifications :) See: http://gtk.php.net/manual/en/about.php and http://cvs.php.net/co.php/php-gtk-doc/dbxml/phpgtkdoc.dtd Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
