I'm beginning to think that because we don't actually conform to DocBook anyway, we might as well do some small customization to the DTD and try get the changes (or something that provides similar functionality) to 6.0, even if it takes a few years. Before my reasoning why we should customize the DTD, some snippets out of the current DocBook documentation.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - funcsynopsis [...] Description A FuncSynopsis contains the syntax summary of a function prototype or a set of function prototypes. The content model of this element was designed specifically to capture the semantics of most C-language function prototypes (for use in UNIX reference pages). This is one of the few places where DocBook attempts to model as well as describe. Using FuncSynopsis for languages that are unrelated to C may prove difficult. [...] Future Changes Future versions of DocBook may provide additional environments for describing the syntax summaries of functions in other programming languages. [...] funcprototype Synopsis Content Model funcprototype ::= (funcdef, (void|varargs|paramdef+)) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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-->]]> <!-- Class: Type of the Parameter; no default --> The last change is there just to stay compatible with the current way we write the documentation, and could(|should?) be removed if we change the DTD after fixing the current documentation. The first two would allow us to model PHP functions the way they really behave. For example: <funcprototype> <funcdef>int <function>foo</function></funcdef> <paramdef>int <parameter>bar</parameter></paramdef> <optional> <paramdef>int <parameter>baz</parameter></paramdef> <paramdef>int <parameter>aaa</parameter></paramdef> <optional> <paramdef>int <parameter>bbb</parameter></paramdef> <paramdef>int <parameter>ccc</parameter></paramdef> </optional> </optional> </funcprototype> See how optional arguments could be grouped together, and later optional arguments be made depented on on previous ones. 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. 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> Was this actually forbidden in the old DTD, or were we all, including me, just too stupid to see it? (Hartmut should prepare to rewrite his RFC...) -- Jouni
