Hello.
I've been wrestling for a while with docbook and xxe to produce documentation
for the php-xmlrpc library.
The produced html is in fact prefect for everything but function prototypes.
Finally today decided to read the DocBook handook, to see what I was getting it
wrong.
As far as I can tell, the problem lies mostly in the docbook definition itself,
which is heavily eskewed towards C language.
What I have in the xml file is similar to this: a funcprototype, with many
funcdefs (these are actually method definitions, but I see no mention of the
possibility of having multiple method definitions in the docbook book...)
The final result should look like this (at least, it did when some sgml tool
used was used in the past to produce the html):
$myVal = new xmlrpcval();
$myVal = new xmlrpcval($stringVal);
$myVal = new xmlrpcval($scalarVal, "int" | "boolean" | "string" | "double" |
"dateTime.iso8601" | "base64");
$myVal = new xmlrpcval($arrayVal, "array" | "struct");
note that:
1a - the '$myVal = new ' text is not the return type of the function, but a
hint about usage. Since php is basically loosely typed, there is little value
in providing a formal type specification. But docbook states that any text in a
'funcdef' except 'function' element is supposed to be the return type...
1b - parameter $stringval has no enforced type: it hints to use a string, but
if given an integer or float the function will use it correctly
2 - the first function definition takes no parameters
3 - in the 3rd and 4th definitions, the 2nd parameter is not given with a name,
but only with a list of possible values
the problems I encounter are:
a) with no parameters, there is an almost-empty line in the HTML generated,
which contains only a single semicolon char (ugly!)
b) I cannot seem to find a valid solution to specify the '"a" | "b" | "c"'
syntax: as per the docbook spec, this is not a 'parameter' element, but rather
an 'initializer'. Unfortunately, XXE seems to ignore any content it finds in a
paramdef element, unless it contains a parameter element. But the docbook dtd
does not mandate the parameter as necessary.
c) since I give no type definition for the first parameter, I see no need to
have it repeated on a line by itself in the generated documentation
Are there known workarounds?
Thanks for help
Gaetano Giunta
PS: the xml fragment I am using is the following:
<funcsynopsis>
<funcprototype>
<funcdef>$myVal = new <function>xmlrpcval</function></funcdef>
<paramdef></paramdef>
</funcprototype>
<funcprototype>
<funcdef>$myVal = new <function>xmlrpcval</function></funcdef>
<paramdef><parameter>$stringVal</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>$myVal = new <function>xmlrpcval</function></funcdef>
<paramdef><parameter>$scalarVal</parameter></paramdef>
<paramdef><initializer>"int" | "boolean" | "string" | "double" |
"dateTime.iso8601" | "base64"</initializer></paramdef>
</funcprototype>
<funcprototype>
<funcdef>$myVal = new <function>xmlrpcval</function></funcdef>
<paramdef><parameter>$arrayVal</parameter></paramdef>
<paramdef>"array" | "struct"</paramdef>
</funcprototype>
</funcsynopsis>
