This is an old revision of the document!

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="" xmlns:xlink="" role="noversion//">

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.

How do I add an external link to the documentation?

  • All external links are added to doc-base/entities/global.ent
  • Add the link there (to global.ent)
  • The global.ent markup might look like: <!ENTITY "">
  • Add the link to the documentation (foo.xml)
  • The markup might look like: <link xlink:href="&;">google spec</link>
  • Be sure the file understands the namespace with xmlns:xlink="" in the root element

I made a change to a file but want to revert this change, how?

  • To merge a file to the previous state: svn merge -rHEAD:PREV filename.xml
  • Then, to commit it: svn commit filename.xml -m “reverted previous commit”

I'm about to document a new PHP extension… how should I start?

  • Use the script found within phpdoc/doc-base/scripts/docgen/*
  • Example: $ php docgen.php -h
  • Example: $ php docgen.php -e simplexml -o outdir
  • It creates the skeletons that you edit then commit

I created skeletons that contain a bunch of default text, should I commit it?

  • No, edit the files before commit.
  • Reason 1: Translators
  • Reason 2: Temporary often becomes permanent, and bogus text is not good

I documented an extension but it's not building. Why?

  • Likely because it has not yet been added to doc-base/
  • So, add the book to the appropriate reference location there. Open file for examples.
  • Or, configure.php is failing… the error should help

I want to contribute to the PHP Manual, how?

How do I build and/or test the manual locally?

  • Use phpdoc/configure.php to validate and then phd to build
  • To validate en: $ php configure.php
  • To validate fr: $ php configure.php --with-lang=fr (Change fr to your given language code)
  • To build: $ phd -d .manual.xml
  • Note: Building is not required, all you must do is check the diff and be sure it validates

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

In the changelog, which order do the PHP versions go?

  • Newest PHP versions go above the older ones

In the changelog, a change happened in two PHP versions. How do I enter this?

  • Multiple versions are separated by a comma, with the lesser version first. Example: <entry>5.2.11, 5.3.1</entry>

How do I add markup for a configure option?

  • Example: <option role="configure">--enable-debug</option>

When adding a <note>, should I add a <title>?

  • Typically titles are useful for notes, but it's not required.
  • Syntax: <note><title>foo</title><para>note contents</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: phpdoc/en/extname/version.xml
  • Changes to functions, like added parameters, are documented within changelogs for each page
  • Example Text: Feature X has been available since PHP X.Y.Z
  • TODO: Research other ways, and the best way, to write this text (including dealing with code examples)

Why does everyone care so much about whitespace?

  • See the following article: whitespace
  • XML is one space, PHP example code is four, and max width is ~78 characters
  • Exceptions: <refpurpose> is on one line, …

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.
  • Example: <methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>false</initializer></methodparam>

Do I need to edit these entities* files?

  • No, these are auto-generated by the configure process
  • Examples: entities/file-entities.ent and en/reference/foo/
  • Also, do not commit them

How do I create a patch?

  • In the command-line, go to the SVN directory:
  • cd /path/to/phpdoc/svn
  • To diff the entire repository: svn diff
  • To diff a single file: svn diff foo.xml
  • Consider piping the diff to a file, so: svn diff foo.xml > mypatch.txt

How do I apply a patch?

  • Assuming the file with the patch is named apatch.txt
  • Go to the directory with the files to be patched
  • And run this command: patch -p0 < apatch.txt

Is there an online editor?

  • Yes and No.
  • Yes one exists in SVN and is being worked on.
  • No it's not yet in use.

How often is the documentation built?

  • Weekly on mirrors, several times daily on the doc server
  • For specifics, see the doc builds article

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
  • 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? Or undocumented (proto only) 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

Undocumented documentation (skeletons exist, but only prototypes and basic information) can be found here:

What .subversion/config settings should I have set? <code> *.xml = svn:eol-style=native;svn:keywords=Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URL </code>

doc/howto/faq.1358998515.txt.gz · Last modified: 2013/01/24 04:35 by philip