Re: Introducing a semantic changelog XML notation

On 11.03.2020 at 09:33, Giovanni Giacobbi wrote:

> I recently did my first contribution to the phpdocs, it was a missing
> changelog entry for mb_convert_case(). For the first time I saw the syntax
> of the XML files and I had the immediate feeling a semantic <changelog> XML
> construct is missing.
>
> Given the importance of the changelog (as full time PHP developer I consult
> the "Changelog" section of the manual pages A LOT) I believe it deserves
> its own XML tag instead of using <informaltable>.
>
> I was thinking about something like (a very random idea, not thought
> through yet):
>
> <changelog>
>   <row>
>     <version>7.3.0</version>
>     <entry>Changed this and that.</entry>
>   </row>
> </changelog>
>
> Do you think this kind of change would be accepted? Has this been discussed
> before?
> It would be quite some work to introduce the new markup and create a
> migration script for the existing documentation, so I'm looking for
> preliminary feedback before venturing into this.

Thanks for bringing this up!

Before going further, it is important to know that the PHP manual
conforms to DocBook[1] (currently version 4.5) which defines a rather
strict XML schema to which we would have to adhere.  Since it doesn't
define a <changelog> element, we can't invent one.

Still, there may be room for improvement regarding the changelogs.  I
wonder whether a table is really suitable; to me, some kind of list
would make more sense.

Thanks,
Christoph

[1] <https://docbook.org/>