Migrate PHP Documentation schema to DocBook 5.2

Girgias commented 4 months ago

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:

[x] 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) (#3331)
[x] 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. (#3342)
[x] assert() docs: ~~similar issue as above, cannot use <methodsynopsis> tags in a changelog entry~~ it is possible just need to wrap the markup properly. (#3343)
[x] reference/pdo_cubrid/reference.xml: (#3344)
[x] reference/mysqlnd/stats.xml: Cannot have a <programlisting> tag inside an <entry> tag. This whole page needs restructuring as using a table seems wrong. (#3357)
[x] reference/intl/*-constants.xml files: Missing a <title> tag just after opening a <section> tag (#3370)
[x] exif_read_data() docs (#3345)
[x] curl_multi_setopt() docs: Describing a callable with <methodsynopsis> for a constant option in an <entry> tag (#3383)
[x] curl_setopt() docs: same a previous item, those constants probably need to be moved and rewritten/marked (#3383)
[x] reference/parle/pattern.matching.xml: In <section xml:id="parle.regex.grouping"> There is a nested table that makes no sense. (#3349)
[x] reference/oci8/fan.xml and reference/oci8/taf.xml: Having <section> tags that don't start with a <title> tag (#3329)

Migration Procedure

[x] Relax current <reference> DTD to match DocBook 5.2 (https://github.com/php/doc-base/pull/122)
[ ] Convert legacy <phpdoc:*> to a DocBook 5.2 equivalence (https://github.com/php/doc-en/pull/3415, https://github.com/php/php-src/pull/14351)
[x] 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 (https://github.com/php/doc-base/pull/123)
[ ] Use jing to indicate RelaxNG schema conformance issues instead of libxml
[ ] Enable RelaxNG validation

haszi commented 3 months ago

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 commented 3 months ago

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: https://github.com/php/doc-base/compare/master...Girgias:doc-base:docbook-5

php / doc-en