doc:scratchpad:howto

This is an old revision of the document!


Quick guide for improving the existing PHP documentation

Getting setup

What you need is:

Source files of the PHP Manual

They are stored in a SVN module named 'phpdoc'. See also the generic generic php.net SVN instructions. And these examples use the svn command but other methods exist, like TortoiseSVN for Windows users.

$ svn checkout http://svn.php.net/repository/phpdoc
Using TortoiseSVN on Windows to do a checkout
  • First off, download and install TortoiseSVN from its website: http://tortoisesvn.net/
  • Open a new explorer window and go to the folder you wish to do a checkout in
  • Right click anywhere in the blank area to spawn the context menu, select “SVN Checkout...”
  • A new window will popup asking for details about the checkout, these values will be remembered, so you will not need to enter them again
  • Enter the following URL: “http://svn.php.net/repository/phpdoc”, then OK to begin the checkout. If you're prompted to enter a password while checking out, then type in “phpfi” and OK
  • When the checkout is complete, then it should have created a directory called “phpdoc” where the php documentation source tree will be
The build system

This renders the DocBook XML into other formats, like the HTML you see at php.net. It's named PhD (See: PhD install guide)

$ pear channel-discover doc.php.net
$ pear install doc.php.net/phd-beta
A text editor

Any will do

Knowledge
Everything working

Before you get started documenting, make sure the tool chain and checkout are okay. To do so, consider the following scenario:

$ phd -V (check to see if phd is installed, and in the path)
$ cd phpdoc (make the manual sources your current directory)
$ php configure.php -V (check to see if this works)
$ php configure.php (This will create a huge .manual.xml file which PhD uses to render the docs)
$ phd -d .manual.xml -f xhtml -t chunkedhtml (Creates an html/ folder with a few thousand files)

Poke around the html/ directory and open up some of the files in you favorite browser to see if everything is fine.

Knowing the structure

The documentation for extensions is located in:

/phpdoc/en/trunk/reference/extension_name/

For example, the SVN extension documentation exists in:

/phpdoc/en/trunk/reference/svn/

There you'll find several files:

  • book.xml (Acts as the container for the extension and contains the preface. Other files (like examples.xml are included from here)
  • setup.xml (Includes setup, install and configuration documentaiton)
  • constants.xml (Lists all constants the extension declares, if any)
  • configure.xml (Usually this information is in setup.xml, but if the file exists it is magically included into setup.xml)
  • examples.xml (Various examples)
  • foo.xml (Example, foo can be anything specific to a topic. Just be sure to include via book.xml)

A procedural extension (like SVN) also has:

  • reference.xml (container for the functions, rarely contains any info)
  • functions/ (folder with one XML file per function that the extension declares)

And OO extensions (such as imagick) contain:

  • classname.xml (container for the methods defined by the class, contains also basic info about it)
  • classname/ (folder with one XML per method that the class declares)
  • Note: “classname” is the lowercased name of the class, not a literal file or directory name.

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!

doc/scratchpad/howto.1249385527.txt.gz · Last modified: 2017/09/22 13:28 (external edit)