Jouni Ahto wrote:
> So, I take this to mean that DocBook isn't even meant to be the exactly right
> DTD for our documentation purposes, although it could become that in the
> future. The content model of funcprototype actually makes it impossible to
> correctly describe the way how PHP functions take arguments, so we should
> change it.
>
> The proposed changes:
>
> --- dbpoolx.mod Mon Mar 12 15:49:18 2001
> +++ dbpoolx.mod.modified Sat Oct 20 13:45:13 2001
> @@ -3705,7 +3705,7 @@
>
> <!ENTITY % funcprototype.element "INCLUDE">
> <![%funcprototype.element;[
> -<!ELEMENT funcprototype %ho; (funcdef, (void | varargs | paramdef+))>
> +<!ELEMENT funcprototype %ho; (funcdef, (void | varargs | (optional | paramdef)+))>
> <!--end of funcprototype.element-->]]>
>
> <!ENTITY % funcprototype.attlist "INCLUDE">
> @@ -6493,7 +6493,7 @@
>
> <!ENTITY % optional.element "INCLUDE">
> <![%optional.element;[
> -<!ELEMENT optional %hh; (%cptr.char.mix;)*>
> +<!ELEMENT optional %hh; (paramdef+ | %cptr.char.mix;)*>
> <!--end of optional.element-->]]>
>
> <!ENTITY % optional.attlist "INCLUDE">
> @@ -6513,7 +6513,7 @@
>
> <!ENTITY % parameter.element "INCLUDE">
> <![%parameter.element;[
> -<!ELEMENT parameter %hh; (%smallcptr.char.mix;)*>
> +<!ELEMENT parameter %hh; (optional | %smallcptr.char.mix;)*>
> <!--end of parameter.element-->]]>
>
> I'd like to hear Jirka's comments about alternative ways of doing this.
> Preferably in a way that has some chance to get accepted into DocBook 6.0.
If you want to customize DTD it is always better to create customization
layer than to directly edit existing DTD. With this approach it is much
more easy to upgrade to new version DocBook which is used as a base for
your DTD. The customization DTD might look like:
<!-- PHPBook DTD 1.0 (based on DocBook 4.1.2) -->
<!ENTITY % docbook PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'
'/path/to/local/copy/of/docbookx.dtd'>
%docbook;
<!ELEMENT funcprototype %ho; (funcdef, (void | varargs | (optional |
paramdef)+))>
<!ELEMENT optional %hh; (paramdef+ | %cptr.char.mix;)*>
<!ELEMENT parameter %hh; (optional | %smallcptr.char.mix;)*>
In PHPBook documents you then would use this DTD instead of standard
DocBook DTD.
I think that change to DocBook DTD which you propose would be useful in
general. I suggest you to post this request as RFE for DocBook DTD at
the sourceforge pages. DocBook Technical Commitee has meatings each
month, so they should discuss it quite early.
> Speaking about a former RFC that I haven't made much noise of lately... the
> current DTD makes it very easy to split the function reference to smaller
> pieces, because the following is allowed:
>
> <part>
> [...]
> <chapter>
> <title>Database functions</title>
> [here go references...]
> </chapter>
> [...]
> <chapter>
> <title>Mathematical functions</title>
> [here go references...]
> </chapter>
> [...]
> </part>
And you can even subdivide chapters by sections:
<part>
[...]
<chapter>
<title>Database functions</title>
<section>
<title>MySQL</title>
... refentries for MySQL here...
</section>
<section>
<title>PostgreSQL</title>
... refentries for pgsql here...
</section>
[...]
</chapter>
[...]
</part>
Jirka
-----------------------------------------------------------------
Jirka Kosek
e-mail: [EMAIL PROTECTED]
http://www.kosek.cz
