i've now finished the final steps needed for the long due update
to the current DocBook XML DTD release, version 4.1.2
the last big showstopper have been the funcion prototype conversions
(actualy those with optional parameters), and as we have quite a lot
of these automatic conversion was a must have here ...
Right now a function parameter description (aka prototype) looks
like this:
<!-- DocBook 3 style -->
<funcsynopsis>
<funcprototype>
<funcdef>array <function>array_change_key_case</function></funcdef>
<paramdef>array <parameter>input</parameter></paramdef>
<paramdef>int <parameter><optional>case</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
This doen't work with the DocBook 4 DTD due to the <optional> tags.
In DocBook 4 these are only allowed within <replaceable>.
As conversion of the <funcsynopsis> areas was needed anyway i decided
to switch to the new <methodsynopsis> for several reasons:
- optional arguments are specifiable via attributes instead of tags
- makes processing in the stylesheets easier
- less typing :)
- documentation of classes is now possible with <classsynopsis>,
class methods should use <methodsynopsis>, so with using them
for simple functions, to, we prepare for being consistent with
upcoming class ducumentations
The new paramter descriptions now look like this:
<!-- DocBook 4 style -->
<methodsynopsis>
<type>array</type>
<methodname>array_change_key_case</methodname>
<methodparam>
<type>array</type>
<parameter>input</parameter>
</methodparam>
<methodparam choice="opt">
<type>int</type>
<parameter>case</parameter>
</methodparam>
</methodsynopsis>
So what has changed:
- <funcsynopsis> is replaced by <methodsynopsis>
- <funcprototype> is no longer needed
- parameter and return types have to be enclosed
in <type>...</type> (a good thing IMHO)
- <paramdef> is replaced by <methodparam>
- optional parameters are declared by setting
the 'choice' attribute in <methodaram> to
'opt', no extra tag needed
I've commited conversion code to be used with the
process.php script, you can convert your xml files
for testing by executing
cd scripts; php -q process.php func2methodsyn.php ../en
you need to have ext/sablot enabled in the php
executable you use for conversion as the actual
conversion is done by XSLT code
configure has already been changed to check for the
use of <methodsynopsis> and to use the DocBook 4 DTD
in this case, so you can play around with this
(on a backup copy of your phpdoc tree i'd suggest)
i have tested this for the english tree only for now,
some DocBook4 compatibility changes have already been
applied to the other languages, too, but i'm rather
sure that small inconsistencies still exist
--
Hartmut Holzgraefe [EMAIL PROTECTED] http://www.six.de +49-711-99091-77
