Re: Introducing a semantic changelog XML notation

On Wed, 11 Mar 2020 at 10:26, Christoph M. Becker <[email protected]> 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