-
Notifications
You must be signed in to change notification settings - Fork 717
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Migrate PHP Documentation schema to DocBook 5.2 #3326
Comments
Maybe we can convert some of the tooling (e.g. |
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 |
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) (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 theassert()
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 useit is possible just need to wrap the markup properly. (Make assert() Changelog section DocBook 5.2 conformant #3343)<methodsynopsis>
tags in a changelog entryreference/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
andreference/oci8/taf.xml
: Having<section>
tags that don't start with a<title>
tag (Fix markup issues in OCI8 extension docs #3329)Migration Procedure
<reference>
DTD to match DocBook 5.2 (Relax <reference> tag DTD doc-base#122)<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)<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)jing
to indicate RelaxNG schema conformance issues instead of libxmlThe text was updated successfully, but these errors were encountered: