Migrate PHP Documentation schema to DocBook 5.2

[Girgias]

DocBook 5.2 has finally been released: https://www.oasis-open.org/2024/02/13/the-docbook-schema-version-5-2-oasis-standard-published/

The primary motivation to migrate to this new version is to be able to use the new <enumsynopsis> tag.

However, there a some issues with the current documentation which makes this migration challenging.

RelaxNG Schema

The new schema is only provided as a RelaxNG schema, whereas most of our tooling expects a DTD.
I have made progress in checking the documentation against it, but this required compiling jing-trang locally to check what is causing issues. It is likely we will need to have this on CI somehow to improve the debugging experience for new contributors.

Legacy custom markup

Classes, Interfaces, and Exceptions use a custom phpdoc: tag, and need to be converted to a structure that fits the DocBook schema, I have written a script that converts the relevant files to a new markup, but this does not validate the schema yet.

Turns out jumping directly to DocBook 5.2 simplifies some stuff as we just need to replace those tags with <reference>.

However, our "new" markup for extending classes/implementing interfaces doesn't comply :(
There seems to either be a bug in the DocBook 5.2 schema, or an undocumented BC break. Trying to contact the relevant people about this issue.

Minor schema violation issues

Various files do not follow the DocBook schema properly and need to be fixed some bigger issues are:

• features/commandline.xml: Table on line 1705 has a warning in an entry (the previous PHP 5 changelog era table should be fully integrated and removed) (CLI docs: Remove PHP 5 era changelog and rework markup #3331)
• reference/info/constants.xml: Cannot use the warning entity in an <entry> tag in the assert() related constant table. Ideally, this constant table should be converted to a list. (Convert info constant tables to variablelists #3342)
• assert() docs: similar issue as above, cannot use <methodsynopsis> tags in a changelog entry it is possible just need to wrap the markup properly. (Make assert() Changelog section DocBook 5.2 conformant #3343)
• reference/pdo_cubrid/reference.xml: (Make PDO CUBRID DocBook 5.2 conformant #3344)
• reference/mysqlnd/stats.xml: Cannot have a <programlisting> tag inside an <entry> tag. This whole page needs restructuring as using a table seems wrong. (Rewrite MySQLnd statistic page #3357)
• reference/intl/*-constants.xml files: Missing a <title> tag just after opening a <section> tag (Make Intl constant pages DocBook 5.2 conformant #3370)
• exif_read_data() docs (Make exif_read_data() Changelog section DocBook 5.2 conformant #3345)
• curl_multi_setopt() docs: Describing a callable with <methodsynopsis> for a constant option in an <entry> tag (Make cURL docs DocBook 5.2 conformant #3383)
• curl_setopt() docs: same a previous item, those constants probably need to be moved and rewritten/marked (Make cURL docs DocBook 5.2 conformant #3383)
• reference/parle/pattern.matching.xml: In <section xml:id="parle.regex.grouping"> There is a nested table that makes no sense. (Clean-up Parle pattern matching markup #3349)
• reference/oci8/fan.xml and reference/oci8/taf.xml: Having <section> tags that don't start with a <title> tag (Fix markup issues in OCI8 extension docs #3329)

Migration Procedure

• Relax current <reference> DTD to match DocBook 5.2 (Relax <reference> tag DTD doc-base#122)
• Convert legacy <phpdoc:*> to a DocBook 5.2 equivalence ([skip-revcheck] Convert class markup to be compatible with DocBook 5.2 #3415, Generate DocBook 5.2 conformant class synopses pages php-src#14351)
• Relax <classsynopsis> DocBook 5.2 RelaxNG schema to "One or more Object-oriented programming inlines" instead of "One of Object-oriented programming inlines" to match DocBook 5.1 schema (Change <classsynopsis> DocBook 5.2 RelaxNG schema doc-base#123)
• Use jing to indicate RelaxNG schema conformance issues instead of libxml #3912
• Enable RelaxNG validation (Use RelaxNG for validation instead of DTD for DocBook 5.2 doc-base#170)

[haszi]

Maybe we can convert some of the tooling (e.g. doc-base's configure.php) to use DOMDocument::relaxNGValidate() to switch from DTD to RelaxNG schema validation. Do you think that could work?

[Girgias]

Maybe we can convert some of the tooling (e.g. doc-base's configure.php) to use DOMDocument::relaxNGValidate() to switch from DTD to RelaxNG schema validation. Do you think that could work?

So yes that's the plan, but libxml2 is terrible at giving useful errors when the schema fails, and also it somehow doesn't validate the schema properly unless I reload the whole file.

You can see what I have here: php/doc-base@master...Girgias:doc-base:docbook-5

[Girgias]

Closing as this has been achieved.