Re: Introducing a semantic changelog XML notation

On Wed, 11 Mar 2020 at 10:26, Christoph M. Becker <cmbecker69@gmx.de> wrote: > 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. > I apologize, I totally missed that part. I suppose that is already quite a blocker for my suggestion. I'm not very familiar with DocBook, but before I start digging into that, do you know if there is an official extendability strategy? Can't we define a PHP doc namespace and have something like <phpdoc:changelog> together with a transformation rule plugin? Would that be acceptable? 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. > > I think the current rendering is quite ok, I find it very clear and readable. My proposal was about changing the markup to make it neater and less error-prone. I saw there are quite a few discrepancies on the structure of the changelog, the biggest one being some of them having the <informaltable> wrapped in a <para> (942) some not (139), which i find a bit awkward. My target was really to change the markup only of the source file. I believe the documentation is so huge that reducing all the "noise" would be important, focusing on the content. For me, all that <informaltable>/<tgroup>/thead should not be duplicated in thousands of files when we can have a simple <changelog> focusing on the real data, that is the important information. Maybe a custom namespaced <changelog> entity that is transformed in the exact same docbook markup in a sort of pre-processor? Kind regards GG