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 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 spec.google "http://www.google.com/">
• Add the link to the documentation (foo.xml)
• The markup might look like: <link xlink:href="&spec.google;">google spec</link>
• Be sure the file understands the namespace with xmlns:xlink="http://www.w3.org/1999/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/manual.xml.in
• 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?

• First, read the HOWTO
• Check out the sources: $ svn checkout http://svn.php.net/repository/phpdoc/modules/doc-en
• For a translation, change the checkout to phpdoc/modules/doc-{lang} where {lang} is the language code
• ...

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

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/entities.bar.xml * 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. * Demo: http://doc.php.net/editor/