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 18:05] – minor rewording, added 'validation' example 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 Manualwhich are stored in a CVS module named 'phpdoc' (See: [[http://php.net/anoncvs|anoncvs]] for generic php.net CVS instructions) +
-  <code>$ cvs co phpdoc</code> +
-  * The build system, and it's named [[doc:phd|PhD]] (See: [[doc:phd:install|PhD 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, make sure the tool chain and checkout are 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 with a 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) +
- +
-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. +
-<code> +
-$ vim phpdoc/en/reference/strings/strlen.xml +
-$ php configure.php +
-$ cvs commit phpdoc/en/reference/strings/strlen.xml -m "Added SeeAlso strpos()" +
-</code> +
- +
-=== 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: +
- +
-<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. +
- +
-== 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 [[doc:scratchpad:pecldocs|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. +
- +
-<code> +
-$ php configure.php +
-</code> +
- +
-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: +
- +
-<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.1228845954.txt.gz · Last modified: 2017/09/22 13:28 (external edit)