goba Thu Jan 23 05:57:11 2003 EDT
Modified files:
/phpdoc/RFC reference_grouping
Log:
Fix typos, and udpate to current state
Index: phpdoc/RFC/reference_grouping
diff -u phpdoc/RFC/reference_grouping:1.1 phpdoc/RFC/reference_grouping:1.2
--- phpdoc/RFC/reference_grouping:1.1 Sat Jul 27 08:03:16 2002
+++ phpdoc/RFC/reference_grouping Thu Jan 23 05:57:10 2003
@@ -21,43 +21,44 @@
<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.
+What can contain a <reference>? The possible parents 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
+That lead me to think about extending or at least modifying Docbook for
+us to be able to group references. For this reason, I have introduced a
"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
+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
+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...
+There may be other issued using XSLT sheets (not tested).
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
+There were some discussions on the phpdoc 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
+Now as it seems, we have no other way to group <reference>s, than 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 :)
+The php-gtk-doc module also uses a modified version of DocBook, and the
+guys there have no problem with it, so I don't think so we will face
+problems.
See: http://gtk.php.net/manual/en/about.php
and http://cvs.php.net/co.php/php-gtk-doc/dbxml/phpgtkdoc.dtd
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
