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
Last revisionBoth sides next revision
doc:howto:editing [2011/04/06 10:59] – external edit 127.0.0.1doc:howto:editing [2014/06/20 12:26] – replaced with a new guide sobak
Line 1: Line 1:
-==== Editing existing documentation ==== +This page has been removed, in 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 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> +
-  $ 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.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1

Page Tools