We have no problem with it? :) I wouldn't quite go that far, but certainly it's more flexible than staying with the docbook dtd would have been. The only issues I've come across are: 1) we had a clash between a docbook.dtd entity and a phpgtkdoc.dtd entity which went undiagnosed for way too long - make very sure you don't double up on those. 2) it's less straightforward to add an element in a modified dtd because you don't have a manual for it (!) so I'd seriously recommend that whoever writes the modification creates at least a rough guide to it. 3) where we have sub-functions we've a still-unresolved problem regarding how to deal with them. I don't believe this arises anywhere in pure PHP.
James Moore wrote the thing, he's probably the best person to speak to if you're embarking on this blind. ----- Original Message ----- From: "Gabor Hojtsy" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]>; <[EMAIL PROTECTED]> Sent: Friday, July 26, 2002 10:05 AM Subject: [PHP-GTK-DOC] phpdoc function reference grouping > 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-GTK Documentation Mailing List (http://gtk.php.net/) > To unsubscribe, visit: http://www.php.net/unsub.php > -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
