This directory contains source files and a setup for converting PHP's XML documentation into presentation formats like HTML and RTF. You should not have to bother with this unless you are writing documentation yourself, or if you simply are curious about how the XML stuff works.
If you just want to read the documentation, look at: https://www.php.net/docs.php
If you are interested in information about how to set up the tools needed, how to work with Git and DocBook on Linux or Windows, or what conventions you should follow when writing phpdoc files, please refer to the PHP Documentation HOWTO.
The PHP Documentation uses the DocBook 5.2 XML schema.
However, there is one small change between the official Docbook 5.2 schema and the schema used by the PHP documentation:
the <classsynopsis> tag allows "One or more Oriented Object Programming inlines",
like the DocBook 5.1 schema does,
instead of "One Oriented Object Programming inlines".
You can read the HOWTO online at: http://doc.php.net/tutorial/
If you are already working with the phpdoc module, then you can find its XML source in the howto directory of the module, and build it yourself with:
phd -d .manual.xmlHowever, PhD is a separate project which can be read about here: https://wiki.php.net/doc/phd
For a more general git-workflow see the Wiki. Make sure to upload your SSH public key to your account at main.php.net
Check out the sources:
mkdir phpdoc
cd phpdoc
git clone [email protected]:php/doc-en.git en
git clone [email protected]:php/doc-your-language-of-choice.git your-language-of-choice
git clone [email protected]:php/doc-base.gitChange your-language-of-choice if you would like to check out a different language.
The en folder contains the English DocBook source files, and doc-base contains tools
and resources used in all languages.
- Make the change. Use spaces not tabs. Be sure to carefully watch your whitespace!
- cd into the desired clone directory, e.g.
cd en - Look at your unified diff, make sure it looks right and that whitespace changes aren't mixed in:
git diff path/to/file.xml
- Make sure no errors are present, so at the command line in your phpdoc source directory run:
php ../doc-base/configure.php
- If you are translating, remember to add the full Git commit hash of the English file that you are translating
from, to the file's
EN-Revisioncomment. - Commit your changes
git commit path/to/file.xml
Read the HOWTO for more information. After reading the HOWTO, email the phpdoc mailing list ([email protected]) with questions and concerns.
- Copy an existing XML file or use a skeleton from the HOWTO. Rename and place it into the appropriate directory.
- Edit. Be sure no leftover text exists. No tabs either.
- If you are translating, remember to add the full Git commit hash of the English
file that you are translating from, to the file's
EN-Revisioncomment. - cd into the desired clone directory, e.g.
cd en - Now test locally before commit by first running
php ../doc-base/configure.php
- Add the file to your staging area
git add path/to/yourfile.xml
- Commit the file and push it to the git-server
git commit path/to/yourfile.xml git push remote your-branch
- Open a pull request to the main repository via GitHub
<filename> filenames
<constant> constants
<varname> variables
<parameter> a function's parameter/argument
<function> functions, this links to function pages or bolds if
already on the function's page. it also adds ().
<literal> teletype/mono-space font <tt>
<emphasis> italics
<example> see HOWTO, includes many other tags.
<link> internal manual links
<link linkend="language.variables">variables</link>
<link> external links via global.ent
<link xlink:href="&spec.cookies;">mmm cookies</link>
<type> types, this links to the given types manual
page: <type>object</type> -> php.net/types.object
&return.success; see: language-snippets.ent
&true; <constant>TRUE</constant>
&false; <constant>FALSE</constant>
&php.ini; <filename>php.ini</filename>
Be sure to check out global.ent and language-snippets.ent (located within each language's repo) for more information for entities and URLs.
There are various scripts available to ensure the quality of the documentation
and find issues with it, they are located in the scripts/qa/ directory.
There might be some more just in scripts/ but they need to be checked if they
are still relevant and/or given some love.
There are also various scripts to ensure the quality and synchrony of
documentation translations, located in the scripts/translation/ directory.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent