Okay this sounds good, let's do it! The following would go right along with our new refsect1 style, does it appear doable?
<refsect1>
&reftitle.changelog;
<para role="changed-behavior" version="4.3.0">
foo() is binary safe.
</para>
<para role="changed-parameter" version="4.2.0">
The length parameter is optional with a default value of 1024.
</para>
<para role="new-parameter" version="4.1.0">
length
</para>
</refsect1>
The above would output something similar to:
CHANGELOG
------------------------------------------------------- |Version | Role | Description | ------------------------------------------------------- |4.3.0 | .... |foo() is binary safe. | ------------------------------------------------------- |4.2.0 | .... |The length parameter is optional | | | .... |with a default value of 1024 | ------------------------------------------------------- |4.1.0 | .... |length | -------------------------------------------------------
Also, the changelog would go below the return value refsect. If the above format won't work please provide a specific style so we can implement ASAP! Through time we may add additional roles.
If you expect a table layout, why overload simple paragraphs with attributes? If it is going to be a table, then para is not right for the markup IMHO. It does not fit semantically and does not fit into DocBook either. BTW I have not checked, but I don't think docbook has a version attribute which applies to para :) What would be the problem with using table markup for changelogs?
The use of present tense seems appropriate here although one could debate using past tense.
Currently the manual uses past tense AFAIR ("became optional", etc)
Goba
