doc:scratchpad:howto
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
doc:scratchpad:howto [2009/08/04 11:30] – Fix CVS mentions mrook | doc:scratchpad:howto [2011/04/06 10:59] – 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: [[doc/howto]] |
- | ==== Getting setup ==== | + | |
- | + | ||
- | What you need is: | + | |
- | + | ||
- | == Source files of the PHP Manual == | + | |
- | They are stored in a SVN module named ' | + | |
- | < | + | |
- | $ svn checkout http:// | + | |
- | </ | + | |
- | + | ||
- | == Using TortoiseSVN on Windows to do a checkout == | + | |
- | * First off, download and install TortoiseSVN from its website: [[http:// | + | |
- | * 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: " | + | |
- | * When the checkout is complete, then it should have created a directory called " | + | |
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | == The build system == | + | |
- | This renders the DocBook XML into other formats, like the HTML you see at php.net. It's named [[doc: | + | |
- | + | ||
- | < | + | |
- | $ pear channel-discover doc.php.net | + | |
- | $ pear install doc.php.net/ | + | |
- | </ | + | |
- | + | ||
- | == A text editor == | + | |
- | Any will do | + | |
- | + | ||
- | == Knowledge == | + | |
- | * PHP | + | |
- | * The [[http:// | + | |
- | + | ||
- | == Everything working == | + | |
- | Before you get started documenting, | + | |
- | < | + | |
- | $ 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: | + | |
- | + | ||
- | / | + | |
- | + | ||
- | For example, the SVN extension documentation exists in: | + | |
- | + | ||
- | / | + | |
- | + | ||
- | There you'll find several files: | + | |
- | + | ||
- | * // | + | |
- | * // | + | |
- | * // | + | |
- | * // | + | |
- | * // | + | |
- | * //foo.xml// (Example, foo can be anything specific to a topic. Just be sure to include via // | + | |
- | + | ||
- | A procedural extension (like SVN) also has: | + | |
- | + | ||
- | * // | + | |
- | * // | + | |
- | + | ||
- | And OO extensions (such as imagick) contain: | + | |
- | + | ||
- | * // | + | |
- | * // | + | |
- | + | ||
- | * Note: "// | + | |
- | ==== Editing existing documentation ==== | + | |
- | Simply open the files and edit them. Remember to follow the " | + | |
- | < | + | |
- | $ vim phpdoc/ | + | |
- | $ php configure.php | + | |
- | $ svn commit -m "Added SeeAlso strpos()" | + | |
- | </ | + | |
- | + | ||
- | ==== Adding new documentation ==== | + | |
- | + | ||
- | When adding new functions or methods, there are a couple | + | |
- | + | ||
- | == Option A: Copy skeleton files == | + | |
- | This involves copying the skeleton files into the correct location: | + | |
- | + | ||
- | < | + | |
- | cp / | + | |
- | cp / | + | |
- | </ | + | |
- | + | ||
- | * Note: " | + | |
- | * Note: " | + | |
- | * Note: " | + | |
- | + | ||
- | == Option B: Generating files using docgen == | + | |
- | The docgen script is found within the php documentation (phpdoc/ | + | |
- | + | ||
- | ==== Testing the changes ==== | + | |
- | + | ||
- | Methods and functions are automagically included into the hierarchy so you don't have to " | + | |
- | + | ||
- | < | + | |
- | $ 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 " | + | |
- | + | ||
- | 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: | + | |
- | + | ||
- | < | + | |
- | $ cvs diff -u > 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 [[http:// | + | |
- | + | ||
- | 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.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1