doc:scratchpad:howto

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
doc:scratchpad:howto [2008/12/09 17:42] – added a few examples to "getting started" philipdoc:scratchpad:howto [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 1: Line 1:
-===== Quick guide for improving the existing PHP documentation ===== +This page has been removed, in favor of [[http://doc.php.net/tutorial/|new guide]]
- +
-=== Getting setup === +
- +
-What you need is: +
-  * Source files of the PHP Manual, which is stored in a CVS module named 'phpdoc' (See: [[http://php.net/anoncvs|anoncvs]]) +
-  <code>$ cvs co phpdoc</code> +
-  * The build system, and it's named [[doc:phd|PhD]] ([[doc:phd:install|See: install guide]]) +
-  <code>$ pear channel-discover doc.php.net +
-$ pear install doc.php.net/phd-beta</code> +
-  * A text editor (any will do) +
-  * Knowledge of the [[http://doc.php.net/php/dochowto/chapter-conventions.php|coding standards]]:  +
- +
-Before you get started documenting you should make sure the tool chain and your checkout is okay. To do so, consider the following scenario: +
-<code> +
-  $ 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 few thousand files) +
-</code> +
- +
-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/reference/extension_name/ +
- +
-For example, the SVN extension documentation exists in: +
-  +
-  /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 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) +
- +
-For procedural extension (like SVN) you also have: +
- +
-  * //reference.xml// (container for the functions, rarely contains any info) +
-  * //functions///    (folder with one XML file per function that 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 one XML per method that the class declares) +
- +
-  * Note: "//classname//" is the lowercased name of the class, not a literal file or directory name. +
- +
-=== Adding new documentation === +
- +
-When adding new functions or methods you start by copying the skeleton files into the correct location: +
- +
-<code> +
-  cp /phpdoc/RFC/skeletons/method.xml classname/methodname.xml   (for new methods) +
-  cp /phpdoc/RFC/skeletons/function.xml functions/functionname.xml (for new functions) +
-</code> +
- +
-  * 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 new file (from the skeleton) with as much detail as possible. +
- +
-To make changes to existing documentation just open the files and edit them. Remember to follow the "coding standard" described in the documentation howto. +
- +
-After that its time to test it. +
- +
-=== 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. +
- +
-Now its time to check the rendering: +
- +
-<code> +
-  $ phd -d .manual.xml -f xhtml -t chunkedhtml +
-</code> +
- +
-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: +
- +
-<code> +
-  $ cvs diff -u > changes.patch +
-</code> +
- +
-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. +
- +
-And later committing them yourself +
- +
-== Committing patches == +
- +
-If you have CVS karma then there is no need to create patches... just commit!  +
- +
doc/scratchpad/howto.1228844555.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools