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/19 07:06] – typo kalledoc: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 == +
-They are stored in a CVS module named 'phpdoc'. See also the [[http://php.net/anoncvs|generic generic php.net CVS instructions]]. And these examples use the cvs command but other methods existlike [[http://www.tortoisecvs.org/|TortoisCVS]] for Windows users. +
-Assuming no CVS account (Password for user //cvsread// is //phpfi//): +
-<code> +
-$ cvs -d :pserver:cvsread@cvs.php.net:/repository login +
-$ cvs -d :pserver:cvsread@cvs.php.net:/repository checkout phpdoc +
-</code> +
-The key information: Server: cvs.php.net User: cvsread Pass: phpfi CVS Module: phpdoc +
- +
-== Using TortoirseCVS on Windows to do a checkout == +
-  * First off, download and install TortoirseCVS from its website: [[http://www.tortoisecvs.org/]] +
-  * 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 "CVS 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 CVSROOT: ":pserver:cvsread@cvs.php.net:/repository" and enter "phpdoc" in the module field, 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 english 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 [[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 == +
-  * PHP +
-  * The [[http://doc.php.net/php/dochowto/chapter-conventions.php|coding standards]]:  +
- +
-== Everything working == +
-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> +
-$ cd phpdoc +
-$ 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). On Windows you may use an external utility to create an archive such as [[http://www.rarsoft.com/|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 CVS karma then there is no need to create patches... just commit!  +
- +
doc/scratchpad/howto.1229670362.txt.gz · Last modified: 2017/09/22 13:28 (external edit)