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
 

Reply via email to