repository·master·Indexed 18 days ago
https://github.com/php/doc-baseBase source files and tools for converting PHP documentation from DocBook 5.2.1 XML into formats like HTML and RTF. Includes the PhD build tool, guidelines for authors and translators, and a suite of QA scripts (such as qaxml-tags.php and qaxml-attributes.php) to ensure structural consistency and XML validity in the PHP Manual.
The PHP documentation is a multi-stage pipeline that converts XML source files into the PHP pages seen on php.net/manual. The process involves four distinct components:
.php files. It also generates search indices (JSON), CSS, images, and Table of Contents (TOC) files..php files. It provides the logic for page headers (navigation, search, breadcrumbs) and footers (copyright, contribution notes).systems@php.net.When providing code examples, choose the correct entity based on whether the output is deterministic:
&example.outputs;: Use this when the output is guaranteed to be identical under all conditions.&example.outputs.similar;: Use this when the output might vary between different executions or different machine environments.When contributing to the PHP manual, the following terms are used:
doc-en@lists.php.net).Note on Brazilian Portuguese: For the Git repository, use pt_br, but for the mailing list suffix, use pt-br.
The PHP Manual sources are organized by topic and extension. For extension documentation, files are located in reference/extension_name/.
General Extension Files:
book.xml: The main container for the extension; includes other files (like examples.xml) and contains the preface.setup.xml: Contains setup, installation, and configuration documentation.configure.xml: If present, this is automatically included into setup.xml.constants.xml: Lists constants declared by the extension.examples.xml: Contains various usage examples.versions.xml: Contains version information.[topic].xml: Custom topic files (e.g., foo.xml) must be explicitly included via book.xml.Procedural Extensions (e.g., calendar):
reference.xml: Container for the extension's functions.functions/: A directory containing one XML file per declared function.Object-Oriented (OO) Extensions (e.g., imagick):
classname.xml: Container for the methods of a class, including basic class information.classname/: A directory containing one XML file per method declared by the class. Note that classname refers to the lowercased name of the class.language-defs.ent: Contains local XML entities used by the language (e.g., main part titles).language-snippets.ent: Contains longer, frequently used translated XML snippets (e.g., warnings, notes).translation.xml: Stores central translation metadata (intro text, translator list). This file is unique to translation trees and is not in the English source.The web-php repository is the runtime environment for php.net. It serves the .php files generated by PhD and provides the functional logic for the site's UI components:
PhD is the rendering engine that transforms the combined XML, version files, and modification history files (produced by doc-base) into the final .php documentation pages.
Key responsibilities include:
.php files containing metadata (title, breadcrumbs, source path, last modified date, contributor list) and calls to web-php functions for headers and footers.search-index and search-description JSON files.The PHP Manual uses two distinct patterns for xml:id attributes. Using the wrong pattern or duplicating IDs can cause build issues.
Structural IDs: Used for linking and chunking on DocBook elements (like <chapter> or <section>).
folder.id (single dot separator).configure.php script will generate warnings if it finds and removes duplicate Structural IDs.XInclude IDs: Used as targets for XIncludes.
folder.id..local (double dot separator).configure.php script will remove duplicate XInclude IDs without generating warnings.Summary Table:
| ID Type | Pattern | Purpose |
|---|---|---|
| Structural | folder.id | Linking/Chunking |
| XInclude | folder.id..local | XInclude targets |
To ensure translations stay synchronized with the English source, every translated file must include an EN-Revision comment in its header. This comment contains the Git commit hash of the specific English file version that the translation is based on.
If the commit hash in your translation's EN-Revision matches the current commit hash of the English file, your translation is up-to-date. If they differ, the English source has changed, and your translation needs to be updated to reflect those changes.
<!-- EN-Revision: [commit_hash] Maintainer: [username] Status: ready -->The doc-base tool is responsible for validating and combining documentation XML files. It uses a configure.php script to perform the following operations:
index.php) to include all elements with appropriate IDs.XInclude and XPointer links.