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 spec.google "http://www.google.com/">
Then you can use this syntax in the documentation:
<link xlink:href="&spec.google;">google spec</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
I made a change to a file but want to revert this change, how?
To merge a file to the previous state use
svn merge -rHEAD:PREV filename.xml, then commit your changes.
Do I need to edit these entities* files?
No, these are auto-generated by the configure process, also do not commit them.
What .subversion/config settings should I have set?
*.xml = svn:eol-style=native;svn:keywords=Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URL