Skip to content

Add genphdfiles.php: generate PhD auxiliary files from doc-base#261

Open
lacatoire wants to merge 3 commits into
php:masterfrom
lacatoire:move-genphdfiles
Open

Add genphdfiles.php: generate PhD auxiliary files from doc-base#261
lacatoire wants to merge 3 commits into
php:masterfrom
lacatoire:move-genphdfiles

Conversation

@lacatoire

@lacatoire lacatoire commented Jul 8, 2026

Copy link
Copy Markdown
Member

Following #253 (comment), this moves the generation of the PhD auxiliary files (version.xml, sources.xml, fileModHistory.php) out of doc-base/configure.php into PhD.

genphdfiles.php reads a doc-base/temp/phd-conf.json handoff and writes the three files where the PHP package already consumes them, so configure.php can focus on assembling and validating the XML.

Companion: php/doc-base#318 (removes the generation from configure.php).
Order: merge this first, then the build pipeline calls php phd/genphdfiles.php doc-base/temp/phd-conf.json, then the doc-base PR can land.

Verified byte-identical to current configure.php output on en/fr/de/es/ru. Tests under tests/genphdfiles/.

lacatoire added 2 commits July 7, 2026 22:41
Generates version.xml, sources.xml and fileModHistory.php (previously produced
by doc-base/configure.php) from the doc-base/temp/phd-conf.json handoff, so that
configure.php can focus on assembling and validating the XML.

Companion to a php/doc-base change that removes this generation from
configure.php. Wire into the build pipeline with:
    php phd/genphdfiles.php doc-base/temp/phd-conf.json
@alfsb

alfsb commented Jul 8, 2026

Copy link
Copy Markdown
Member

Suggestions, for now or the far future.

Where the files are saved in the their historical paths (directly inside doc-base), also save then in the idempotent path, inside doc-base/temp/, prefixed with phd and the rest of name in your preference (the old function names of configure shows a nice symmetry).

After this, each filegen function of genphdfiles.php can guads the existence of files in idempotent path, so they not regenerated each time genphdfiles.php runs, making this step very fast while developing PhD (one run of doc-base/configure, many runs of PhD). doc-base/configure.php always erase doc-base/temp, so any files here never go out of sync with the manual.xml generated here.

This will make all the new files siblings of doc-base/temp/manual.xml. In the far future, if/when PhD is changed to input files only from doc-base/temp, all generated files outside doc-base/temp can stop being duplicated, making both doc-base and PhD fully idempotent.

The idempotent/cached/faster bits are very relevant for phd_sources(), but may not be true or relevant for the other files.

@alfsb

alfsb commented Jul 8, 2026

Copy link
Copy Markdown
Member

While the byte-identical result is important for now, this change places these files under full control of PhD, where they belong, so after the move, they can freely be reworked to strictly serve PhD necessities.

Moving the output files to idempotent paths will make their contents fully dependent on doc-base/configure.php runs, as they are now. Other doc-base dependent files can also use doc-base/temp, if there is any.

phd_sources() reads every XML file of the manual, so it dominates the
cost of these generators. When srcdir/temp/ exists (configure.php always
creates and wipes it per run), stash a copy of sources.xml there and
short-circuit to it on the next run. This keeps repeated PhD runs fast
during development without ever going out of sync with manual.xml, which
is regenerated in the same temp/ directory.

The historical sources.xml is still written by the same DOM save, so the
output stays byte-identical.
@lacatoire

Copy link
Copy Markdown
Member Author

@alfsb I was working on it, while you comment. I already pushed the cache in the latest commit (temp/phd-sources.xml, short-circuit on hit, byte-identical historical output, plus a test). Fully agree on the rest: now that PhD owns these files they can be reworked for PhD's needs, and eventually read straight from temp/ so the historical copies go away. Keeping that out of this PR to land the move cleanly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants