(CCing phpdoc@ so others may benefit from this mail) On Mon, Oct 20, 2008 at 17:44, Brandon Savage <[EMAIL PROTECTED]> wrote: > I'm particularly interested in the SVN extension. There are lots of > undocumented functions there. Also, apparently the ImageMagick library needs > some documentation.
Improving the existing documentation is easy, as long as you follow the "Coding Standard" as described at http://doc.php.net/php/dochowto/chapter-conventions.php. All you need is: - phpdoc checkout (cvs -d:pserver:[EMAIL PROTECTED]/repository co phpdoc)[1] - PhD installed (pear install doc.php.net/phd-beta)[2] - Text editor Before you get started documenting you should make sure the tool chain and your checkout is OK: - 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 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. The documentation for extensions is located in: /phpdoc/en/reference/<extensionname>/ For the SVN extension that would be /phpdoc/en/reference/svn/ There you'll find several files: - book.xml (Acts as the container for the extension and contains the preface) - setup.xml (Includes setup, install and configuration docs) - 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) For procedural extension (such as SVN) you also have: - reference.xml (container for the functions, rarely contains any info) - functions/ (folder with 1 XML file per function the extension declares) For OO extensions (such as imagick) you have: - "classname".xml (container for the methods defined by the class, contains also basic info about it) - "classname"/ (folder with 1 XML per method the class declares) Note: "classname" is the lowercased name of the class, not a literal file or directory name. When adding new functions or methods you start by 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. Then you fill out the skeleton as detailed as possible. To make changes to existing documentation just open the files and edit them. Remember to follow the "coding standard" described in the dochowto. After that its time to test it. 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. Now its time to 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. If you edited existing documentation you will have to create a patch: cvs diff -u > changes.patch (will iterate recursively over the directory and push all changes into the changes.patch file) 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). 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. -Hannes [1] Before you can do a checkout you have to login: cvs -d:pserver:[EMAIL PROTECTED]/repository login Then you'll be asked for the password, which is "phpfi" if I remember correctly. For more information on anonymous checkout see: http://php.net/anoncvs [2] Before you can install PhD you have to "discover" the channel: pear channel-discover doc.php.net
