doc:howto:editing

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:howto:editing [2011/04/17 20:03] – fixed phd command (thanks Ulf W) philipdoc:howto:editing [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 1: Line 1:
-==== Editing existing documentation ==== +This page has been removedin favor of [[http://doc.php.net/tutorial/editing.php|new guide]]
-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/trunk/reference/strings/strlen.xml +
-$ php configure.php +
-$ svn commit -m "Added SeeAlso strpos()" phpdoc/en/trunk/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. +
- +
-== 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 classnot 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 -P PHP -f xhtml +
-</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> +
-  $ svn diff > 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 SVN karma then there is no need to create patches... just commit! +
doc/howto/editing.1303070612.txt.gz · Last modified: 2017/09/22 13:28 (external edit)