Frequently Asked Questions
I'm about to document a new PHP extension. How should I start?
Change your working directory to
phpdoc/doc-base/scripts/docgen/ and execute:
php docgen.php -e simplexml -o outdir
It creates the skeletons that you edit, and then commit.
Help is available with following command:
php docgen.php -h.
I created skeletons that contain a bunch of default text, should I commit it?
No! Edit the files, to check the generated content and add more information, before committing. Thinking that it is okay to commit the skeleton files because you will soon come along and flesh them out might seem like a good idea. However, temporary often becomes permanent.
Running configure.php ends up segfaulting, what is up?
There are bugs with certain versions of libxml that cause this, so hacks exist to get around it.
To execute the hack, pass in:
$ php configure.php --disable-segfault-error.
Note: This disables some error checking and beautification but raw errors will be shown.
Note: Usually the problem is a major XML syntax issue.
Is there an online editor?
How do I add a link to a method?
<methodname>Class::method</methodname>. Note that the case does not matter when adding a link.
If a refentry should not emit versioning information, what should I do?
role="noversion" to its
<refentry xml:id="reserved.variables.argc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" role="noversion">
How do I add an external link to the documentation?
All external links are added to
doc-base/entities/global.ent. Markup looks as follows:
<!ENTITY url.google "http://www.google.com/">
Then you can use this syntax in the documentation:
Check out <link xlink:href="&url.google;">Google</link>
Be sure the file understands the
xlink namespace, by using
xmlns:xlink="http://www.w3.org/1999/xlink" in the document element.
When adding a note, should I add a title?
Typically titles are useful for notes, but it's not required.
<note> <title>Foo</title> <para>Note contents are here.</para> </note>
A feature became available in PHP X.Y.Z, how do I document that?
Version information for functions is stored inside
each extension (e.g.
phpdoc/en/extname/versions.xml). Changes to functions,
like added parameters, are documented within the changelog section for each page.
A parameter is optional, how is it documented?
Like normal, except
methodparam receives the
choice="opt" attribute, and
<initializer> tag is used to signify the default value.
I see example.outputs and example.outputs.similar entities, what's the difference?
&example.outputs.similar; entity is used when the output may differ between executions or machines.
&example.outputs; entity output will always, under all conditions, be the same.
I need to add a piece of text to three or more pages, how?
Add the snippet to
en/language-snippets.ent as an entity and link to the entity within the desired pages.
This is done so translators can update one version of this text.
How do I find missing documentation?
Missing functions (no associated XML files) can be found like so (assuming a doc checkout, and PhD is installed):
php doc-base/configure.php phd --docbook doc-base/.manual.xml --package PHP --format php php doc-base/scripts/check-missing-docs.php -d output/index.sqlite
After fixing a build, translation is still not updated on docs server and there are no errors shown
If you just fixed the build of an old translation, it works locally, but it's not updated on the docs
mirror, make sure that you removed
broken-language.txt from the root of your translation.
Do I need to edit these entities* files?
No, these are auto-generated by the configure process, also do not commit them.