doc:scratchpad:howto
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revisionNext revisionBoth sides next revision | ||
doc:scratchpad:howto [2008/10/21 08:23] – initial commit for review, most content stolen from http://marc.info/?l=phpdoc&m=122453079823213 philip | doc:scratchpad:howto [2009/08/04 11:32] – Fix CVS mentions mrook | ||
---|---|---|---|
Line 1: | Line 1: | ||
===== Quick guide for improving the existing PHP documentation ===== | ===== Quick guide for improving the existing PHP documentation ===== | ||
- | + | ==== Getting setup ==== | |
- | === Getting setup === | + | |
What you need is: | What you need is: | ||
- | * Source files of the PHP Manual, which is stored in a CVS module named ' | ||
- | * The build system, and it's named PhD ([[doc: | ||
- | * A text editor (any will do) | ||
- | * Knowledge of the [[http:// | ||
- | Before you get started documenting you should make sure the tool chain and your checkout is okay. To do so, consider | + | == Source files of the PHP Manual == |
+ | They are stored in a SVN module named ' | ||
< | < | ||
- | | + | $ svn checkout http://svn.php.net/repository/ |
- | $ 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) | + | |
</ | </ | ||
- | Poke around the **html/** directory | + | == Using TortoiseSVN on Windows to do a checkout == |
+ | | ||
+ | | ||
+ | * 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 " | ||
- | === Knowing the structure === | + | |
+ | |||
+ | |||
+ | == 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: | The documentation for extensions is located in: | ||
- | / | + | /phpdoc/en/trunk/ |
For example, the SVN extension documentation exists in: | For example, the SVN extension documentation exists in: | ||
- | / | + | /phpdoc/en/trunk/ |
There you'll find several files: | There you'll find several files: | ||
- | * // | + | * // |
* // | * // | ||
* // | * // | ||
* // | * // | ||
+ | * // | ||
+ | * //foo.xml// (Example, foo can be anything specific to a topic. Just be sure to include via // | ||
- | For procedural extension (like SVN) you also have: | + | A procedural extension (like SVN) also has: |
* // | * // | ||
* // | * // | ||
- | For OO extensions (such as imagick) | + | And OO extensions (such as imagick) |
* // | * // | ||
Line 49: | Line 78: | ||
* Note: "// | * Note: "// | ||
- | === Adding new documentation === | + | ==== 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 of options. Either way, the generated (or copied) files will need to be filled out. | ||
- | When adding new functions or methods you start by copying the skeleton files into the correct location: | + | == Option A: Copy skeleton files == |
+ | This involves | ||
< | < | ||
Line 62: | Line 102: | ||
* Note: " | * Note: " | ||
- | Then you fill out the new file (from the skeleton) with as much detail as possible. | + | == Option B: Generating files using docgen == |
+ | The docgen script is found within | ||
- | To make changes to existing documentation just open the files and edit them. Remember to follow the " | + | ==== Testing the changes |
- | + | ||
- | 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 " | Methods and functions are automagically included into the hierarchy so you don't have to " | ||
- | Now its time to check the rendering: | + | < |
+ | $ cd phpdoc | ||
+ | $ php configure.php | ||
+ | </ | ||
+ | |||
+ | When the above outputs something like "All good. Saving .manual.xml... done." then you know it validates. | ||
< | < | ||
- | | + | $ phd -d .manual.xml -f xhtml -t chunkedhtml |
</ | </ | ||
Line 81: | Line 123: | ||
If everything is looking good, its time to post the changes. | If everything is looking good, its time to post the changes. | ||
- | + | ==== Committing the changes | |
- | === Committing the changes === | + | |
== Creating patches == | == Creating patches == | ||
Line 89: | Line 130: | ||
< | < | ||
- | $ cvs diff -u > changes.patch | + | $ svn diff > 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). | + | 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. | 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. | ||
Line 100: | Line 141: | ||
== Committing patches == | == Committing patches == | ||
- | If you have CVS karma then there is no need to create patches... just commit! | + | If you have SVN 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