This is an old revision of the document!
Editing existing documentation
Simply open the files and edit them. Remember to follow the “coding standard” described in the documentation howto. And after it validates, commit.
$ vim phpdoc/en/trunk/reference/strings/strlen.xml $ php configure.php $ svn commit -m "Added SeeAlso strpos()" phpdoc/en/trunk/reference/strings/strlen.xml
Adding new documentation
When adding new functions or methods, there are a couple of options. Either way, the generated (or copied) files will need to be filled out.
Option A: Copy skeleton files
This involves copying the skeleton files into the correct location:
cp /phpdoc/RFC/skeletons/method.xml classname/methodname.xml (for new methods) cp /phpdoc/RFC/skeletons/function.xml functions/functionname.xml (for new functions)
- Note: “classname” is the lowercased name of the class, not a literal file name.
- Note: “methodname” is the lowercased name of the method name, not a literal file name.
- Note: “functionname” is the lowercased name of the function name, not a literal file name.
Option B: Generating files using docgen
The docgen script is found within the php documentation (phpdoc/scripts/docgen/) and uses Reflection to generate documentation (DocBook) files. See the PECL Docs section for details.
Testing the changes
Methods and functions are automagically included into the hierarchy so you don't have to “configure” anything, just run “php configure.php” to build the .manual.xml and validate the changes. If no error occur it means you changes validated.
$ cd phpdoc $ php configure.php
When the above outputs something like “All good. Saving .manual.xml... done.” then you know it validates. Now its time to optionally check the rendering:
$ phd -d .manual.xml -f xhtml -t chunkedhtml
This will create a “html/” directory in your current working directory. Open up the files you just added in your browser and make sure everything is fine (the filenames are taken from the “xml:id” attribute on the root element of the XML file).
If everything is looking good, its time to post the changes.
Committing the changes
Creating patches
If you edited existing documentation you will have to create a patch. The following will iterate recursively over the directory and push all changes into the changes.patch file:
$ svn diff > changes.patch
If you added new files you will have to create an archive of the new files you added (tar -cf changes.tar file1.xml file2.xml file3.xml). On Windows you may use an external utility to create an archive such as WinRAR.
Then upload the archive (or patch file) to http somewhere and post the link to phpdoc@lists.php.net including a short summary of what you did.
And later committing them yourself
Committing patches
If you have SVN karma then there is no need to create patches... just commit!