What it will contain:
1) Parameter changes (new, modified, ...)
2) Function changes (new features, new behaviors, ...)
3) PHP Version info for each change
From TODO:
new roles: seealso, newparameter, and changedparameter.
That idea is similar and here's one of the threads on the topic:
http://marc.theaimsgroup.com/?l=phpdoc&m=105612826212630
So rather than just sticking this information in a changelog
we'll want to have php version ids for each change so that
parsing them would be easier (like creating one huge changelog
list somewhere per php version, and adding ability to highlight
changes since a given PHP version via my.php and CSS). Any ideas on implementing this or should we just keep it simple
and write plain old para's? I prefer implementing per version but not sure how yet, do you? :) Implementing my.php can be done later but also be planned for.
Having this information in each parameters definition would get
a little messy so we probably should keep definitions and
changelog entries seperate. Parameter definitions would describe the current behavior.
A possible format:
<changelog>
<changedparameter>
<parameter>length</parameter>
<version>4.2.0</version>
<para>
Became optional with a default value of 1024.
</para>
</changedparameter>
...
</changelog>
Maybe it's not generic enough, could we cover every condition?
<changedbehavior>, <newparameter>, etc. Thoughts?
As the TODO suggests we planned to introduce roles, and not new tags. In fact we are currently not using any nonDocBook tags. It would be good to investigate the available docbook tags to mark up a changelog. BTW I think the detail of the changelog you provided above is too much. We only need filtering for versions IMHO. The, like
<somesecttag id=".....changes">
<para role="changed-parameter" version="4.2.0">
The length parameter became optional with a default value of 1024.
</para>
</somesecttag>
This exact tagging would of course mean that the rendering system need to handle the 4.2.0 version mark, and need to prepend it before the paragraph (at least :). Otherwise we are unable to do it with the current DSSSL sheets. I am not completely unable to tweak DSSSL sheets in such a simple situation copying and customizing existing stuff :)
Goba