Skip to content

Move files specific to main manual into doc-en#5682

Open
alfsb wants to merge 1 commit into
php:masterfrom
alfsb:third-party-ext
Open

Move files specific to main manual into doc-en#5682
alfsb wants to merge 1 commit into
php:masterfrom
alfsb:third-party-ext

Conversation

@alfsb

@alfsb alfsb commented Jul 14, 2026

Copy link
Copy Markdown
Member

This PR is the first step in preparation for https://wiki.php.net/rfc/third_party_ext_documentation . The main objective is to "move" files that are specific to the main manual into doc-en, so doc-base can build each manual with the minimum of conventions.

Also, it intends to stop cross-repositories PRs between manuals and doc-base, even more so in the many piecewise changes that the splitting of manuals may cause.

Many changes in manual.xml already included here:

  • Root <set> is reorganized;
  • Some xmlns re-declarations removed;
  • funcindex.xml is embedded, so &global.function-index; is not necessary anymore;
  • Auto generated files are to be loaded from a temp/ dir, sibling of doc-en (to keep git clean and manual build idempotent).

global.ent is moved as is, to be manually  converted into XML entities later.

If everything goes well, the preamble of manual.xml eventually will contain only two parameter entities, one for text-entities, other for file-entities.

Questions:

  1. This is ok?
    There are many changes to be made in doc-base/configure.php (and probably in PhD) to start building the new external extensions/projects manual. Moving these files here, in particular manual.xml, has the potential of making many of these changes unnecessary.

  2. The root <set> is not missing a xmlns for XInclude?
    Even if the final XML should not include any XInclude in the end, there many intermediary steps there xi:include tags are valid and expected content of manual building.

  3. Is the version="5.2" in root <set> necessary?

  4. funcindex.xml not moved
    This file is small, has no translatable text, so I decided to merge it in manual.xml. But it is referred to by name in PhD and file-entities.php, so it's necessary to open an issue on PhD, noting its future remotion, I presume. This file used/mentioned elsewhere?

  5. acronyms.xml, idem
    I do not plan to move this file, as it appears not to be used directly anywhere. I presume it is used in PhD, to patch all acronym elements. I would like to hear some PhD maintainers or translations, in about "converting" this file into translatable XML entities, keyed by acronym.lower. That will need changes on PhD, of course, but will make acronyms translable. The very first acronym, AKA, "Also Known As", is a good example of the necessity of this part of the manual to be translatable.


As third-party efforts already started, I would like to merge this as soon as possible, but I know this a big change, and a controversial one to boot, so I plan to leave this open at least two weeks. Comments and reviews are very welcome.

@ndossche
ndossche removed their request for review July 15, 2026 07:59
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.

1 participant