php / php/phd

Rendering differences around non significant XML

Open
#265 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
PHP
Stars
91
Forks
59
PR merge metrics
No merged PRs in 30d

Description

While developing the XML trim project, testing showed some differences that may or may not be worth debugging. I think these changes (removal of XML comments and removal of duplicated XML namespaces) surfaced heisenbug, in a very controlled setup, so it is possible to stabilize PhD to not show dependent behaviour in non significant XML changes.

The setup:

phd             1a70b5bd531e4687b64447d0c0a3e33cb9c98714
en              36d18e7d4a32ecfdacc1eb086276ffb1baf0393c
doc-base (prev) 738f18cf429d45eed2698b8cd77d3364ea87f085
doc-base (next) 8eeece936aa2103c0632a22e47791749cb7aa697

php -v
PHP 8.1.2-1ubuntu2.25 (cli) (built: Jul 16 2026 18:32:33) (NTS)

rm -rf output
php doc-base/configure.php -q --with-lang=en
php phd/render.php --color false --package PHP --format php --format xhtml --format bigxhtml --format tocfeed -d doc-base/.manual.xml

These are the major differences observed.

Empty TD

There is a lot of:

<       <td></td>
---
>       <td class="empty">&nbsp;</td>

These, while annoying, does not change the behaviour or rendered manual. The worrie is that XML comments or duplicated namespace somehow affects empty TDs.

Files omitted

There are a lot of files that are emitted with doc-base prev, that are not in doc-base prev. Things like:

Only in doc-base-prev-out/php-chunked-xhtml: intro.apache.html
Only in doc-base-prev-out/php-chunked-xhtml: intro.apcu.html
Only in doc-base-prev-out/php-chunked-xhtml: intro.array.html
...
Only in doc-base-prev-out/php-chunked-xhtml: intro.zmq.html
Only in doc-base-prev-out/php-chunked-xhtml: intro.zookeeper.html
Only in doc-base-prev-out/php-chunked-xhtml: mysqlinfo.intro.html
Only in doc-base-prev-out/php-chunked-xhtml: preface.html

Only in doc-base-prev-out/php-web: intro.apache.php
Only in doc-base-prev-out/php-web: intro.apcu.php
Only in doc-base-prev-out/php-web: intro.array.php
...
Only in doc-base-prev-out/php-web: intro.zmq.php
Only in doc-base-prev-out/php-web: intro.zookeeper.php
Only in doc-base-prev-out/php-web: mysqlinfo.intro.php
Only in doc-base-prev-out/php-web: preface.php

All these files appear to not being published on the main manual, so they also do not block XML trim merge, but is something that worries me more, as now entire files are being created or omitted bases in non-significant XML.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the comparison with doc-base/configure.php, phd/render.php, and doc-base/.manual.xml using the exact revisions and PHP command shown. Compare the generated outputs for empty TDs and omitted files while changing only the XML comments or duplicated namespaces. Done means establishing whether the differences are reproducible and identifying the source or documenting that no stable cause was found.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
build-system, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.