Open Girgias opened 4 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?
Maybe we can convert some of the tooling (e.g.
doc-base
'sconfigure.php
) to useDOMDocument::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
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 customphpdoc:
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) (#3331)reference/info/constants.xml
: Cannot use the warning entity in an<entry>
tag in theassert()
related constant table. Ideally, this constant table should be converted to a list. (#3342)assert()
docs:similar issue as above, cannot useit is possible just need to wrap the markup properly. (#3343)<methodsynopsis>
tags in a changelog entryreference/pdo_cubrid/reference.xml
: (#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. (#3357)reference/intl/*-constants.xml
files: Missing a<title>
tag just after opening a<section>
tag (#3370)exif_read_data()
docs (#3345)curl_multi_setopt()
docs: Describing a callable with<methodsynopsis>
for a constant option in an<entry>
tag (#3383)curl_setopt()
docs: same a previous item, those constants probably need to be moved and rewritten/marked (#3383)reference/parle/pattern.matching.xml
: In<section xml:id="parle.regex.grouping">
There is a nested table that makes no sense. (#3349)reference/oci8/fan.xml
andreference/oci8/taf.xml
: Having<section>
tags that don't start with a<title>
tag (#3329)Migration Procedure
<reference>
DTD to match DocBook 5.2 (https://github.com/php/doc-base/pull/122)<phpdoc:*>
to a DocBook 5.2 equivalence (https://github.com/php/doc-en/pull/3415, https://github.com/php/php-src/pull/14351)<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)jing
to indicate RelaxNG schema conformance issues instead of libxml