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
Next revisionBoth sides next revision
doc:scratchpad:howto [2008/12/09 17:42] – added a few examples to "getting started" philipdoc:scratchpad:howto [2009/06/20 17:56] – added examples.xml and foo.xml, referred to book.xml philip
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 '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:+== 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 exist, like [[http://www.tortoisecvs.org/|TortoisCVS]] for Windows users. 
 +Assuming no CVS account (Password for user //cvsread// is //phpfi//):
 <code> <code>
-  $ phd -V (check to see if phd is installed, and in the path) +$ cvs -d :pserver:cvsread@cvs.php.net:/repository login 
-  $ cd phpdoc (make the manual sources your current directory) +$ cvs -d :pserver:cvsread@cvs.php.net:/repository checkout phpdoc
-  $ 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> </code>
 +The key information: Server: cvs.php.net User: cvsread Pass: phpfi CVS Module: phpdoc
  
-Poke around the **html/** directory and open up some of the files in you favorite browser to see if everything is fine.+== 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
  
-=== Knowing the structure ===+  * **Branching**, If you need to check out a specific branch, for example for PhD then you will need to select the "Revision" tab in the Checkout window. In here select the "Choose branch or tag" option, and enter the branch name hit the OK button to do the checkout for the choosen branch. You may use the "Update list..." button to fetch a fresh list of valid branches for the current module you are about to checkout. 
 + 
 + 
 + 
 +== 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: The documentation for extensions is located in:
Line 35: Line 64:
 There you'll find several files: There you'll find several files:
  
-  * //book.xml// (Acts as the container for the extension and contains the preface)+  * //book.xml// (Acts as the container for the extension and contains the preface. Other files (like //examples.xml// are included from here)
   * //setup.xml// (Includes setup, install and configuration documentaiton)   * //setup.xml// (Includes setup, install and configuration documentaiton)
   * //constants.xml// (Lists all constants the extension declares, if any)   * //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)   * //configure.xml// (Usually this information is in setup.xml, but if the file exists it is magically included into setup.xml)
 +  * //examples.xml// (Various examples)
 +  * //foo.xml// (Example, foo can be anything specific to a topic. Just be sure to include via //book.xml//)
  
-For procedural extension (like SVN) you also have:+A procedural extension (like SVN) also has:
  
   * //reference.xml// (container for the functions, rarely contains any info)   * //reference.xml// (container for the functions, rarely contains any info)
   * //functions///    (folder with one XML file per function that the extension declares)   * //functions///    (folder with one XML file per function that the extension declares)
  
-For OO extensions (such as imagick) you have:+And OO extensions (such as imagick) contain:
  
   * //classname//.xml (container for the methods defined by the class, contains also basic info about it)   * //classname//.xml (container for the methods defined by the class, contains also basic info about it)
Line 52: Line 83:
   * Note: "//classname//" is the lowercased name of the class, not a literal file or directory name.   * Note: "//classname//" is the lowercased name of the class, not a literal file or directory name.
  
-=== Adding new documentation ===+==== 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 -m "Added SeeAlso strpos()" phpdoc/en/reference/strings/strlen.xml 
 +</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.
  
-When adding new functions or methods you start by copying the skeleton files into the correct location:+== Option A: Copy skeleton files == 
 +This involves copying the skeleton files into the correct location:
  
 <code> <code>
Line 65: Line 107:
   * Note: "functionname" is the lowercased name of the function 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.+== 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.
  
-To make changes to existing documentation just open the files and edit them. Remember to follow the "coding standard" described in the documentation howto. +==== 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 "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. 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> 
 +$ 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> <code>
-  $ phd -d .manual.xml -f xhtml -t chunkedhtml+$ phd -d .manual.xml -f xhtml -t chunkedhtml
 </code> </code>
  
Line 85: Line 129:
 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 95: Line 139:
 </code> </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).+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. 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 104: Line 148:
  
 If you have CVS karma then there is no need to create patches... just commit!  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

Page Tools