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?

There used to be at edit.php.net. Our wiki contains an overview of the editor and how to use it. Nowadays, changes should be done via GitHub.

How do I add a link to a method?

Use <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?

Add the role="noversion" to its <refentry>. Example:

<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 versions.xml within 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 the <initializer> tag is used to signify the default value.

<methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>false</initializer></methodparam>

I see example.outputs and example.outputs.similar entities, what's the difference?

The &example.outputs.similar; entity is used when the output may differ between executions or machines. The &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. Examples: entities/file-entities.ent and en/reference/foo/entities.bar.xml