PHP Wiki doc:howto

doc:howto:docbook

2008-05-25T20:23:19+00:00

1211746302		current
Line 20:		Line 20:

	DocBook version upgrade history: On January 2, 2007 we upgraded from DocBook 4.1.2 to 4.5 and then to DocBook 5 at around June 20, 2007. These upgrades included changes to most files in the phpdoc CVS repository.		DocBook version upgrade history: On January 2, 2007 we upgraded from DocBook 4.1.2 to 4.5 and then to DocBook 5 at around June 20, 2007. These upgrades included changes to most files in the phpdoc CVS repository.
		+
		+	==== DocBook reference ====
		+
		+	For information about the DocBook DTD, look here: http://www.oasis-open.org/docbook/.
		+
		+	There is a DTD reference for DocBook at: http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html.
		+
		+	Get Going With DocBook, Notes for Hackers: http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html.
		+
		+	You can also find more information and downloads of style sheets and other tools for DocBook in the DocBook Open Repository at: http://docbook.sourceforge.net/.
		+
		+	You can also read the book DocBook: The Definitive Guide online, or buy it at a bookstore, but be warned, that the first edition of the book (currently the only printed edition available) contains outdated information.
		+
		+	There is a great DocBook Wiki, where you can collect information on DocBook editors, transformation tools, etc.

doc:howto:editing

2009-09-09T01:12:13+00:00

	current
Line 1:	Line 1:
	+	==== 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/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:faq

2009-10-24T15:56:15+00:00

1256399715		current
Line 62:		Line 62:
	* Example: %%<option role="configure">--enable-debug</option>%%		* Example: %%<option role="configure">--enable-debug</option>%%

-	//When adding a <note>, should I add a <title>?	+	//When adding a <note>, should I add a <title>?//
	* Typically titles are useful for notes, but it's not required.		* Typically titles are useful for notes, but it's not required.
	* Syntax: %%<note><title>foo</title><para>note contents</para></note>%%		* Syntax: %%<note><title>foo</title><para>note contents</para></note>%%

doc:howto:gettingstarted

2009-09-28T18:43:38+00:00

1252454895		current
Line 22:		Line 22:

	The command-line works fine, download/install the sources (or binaries) from [[http://subversion.tigris.org/]]		The command-line works fine, download/install the sources (or binaries) from [[http://subversion.tigris.org/]]
-
	==== The source files ====		==== The source files ====

	Using SVN, checkout the source files of the PHP manual. These are the files you will edit and commit, and anyone (no account is required) may checkout these files. For example, using the command-line:		Using SVN, checkout the source files of the PHP manual. These are the files you will edit and commit, and anyone (no account is required) may checkout these files. For example, using the command-line:

-	* svn checkout http://svn.php.net/repository/phpdoc/modules/phpdoc-en phpdoc	+	* svn checkout http://svn.php.net/repository/phpdoc/modules/doc-en phpdoc

	That will use svn:externals to checkout both the doc-base and en/ modules, into a local directory named phpdoc. Then, after the above you might:		That will use svn:externals to checkout both the doc-base and en/ modules, into a local directory named phpdoc. Then, after the above you might:
Line 36:		Line 35:
	In other words, this will create a directory named 'phpdoc' with a subdirectory 'en' that contains all of the English files. Now, a translator will instead do something like the following (to checkout German):		In other words, this will create a directory named 'phpdoc' with a subdirectory 'en' that contains all of the English files. Now, a translator will instead do something like the following (to checkout German):

-	* svn checkout http://svn.php.net/repository/phpdoc/modules/phpdoc-de phpdoc-de	+	* svn checkout http://svn.php.net/repository/phpdoc/modules/doc-de phpdoc-de
	* cd phpdoc-de		* cd phpdoc-de
	* vim de/preface.xml en/preface.xml		* vim de/preface.xml en/preface.xml

doc:howto:pecldocs

2009-10-16T20:44:07+00:00

1255725617		current
Line 54:		Line 54:
	}		}
	</code>		</code>
-
	==== Other Notes ====		==== Other Notes ====
	* Docgen may be used to generate specific documentation too, like for individual classes and functions		* Docgen may be used to generate specific documentation too, like for individual classes and functions
Line 64:		Line 63:
	* Feel free to ask phpdoc@lists.php.net for code review, or #php.doc on Efnet		* Feel free to ask phpdoc@lists.php.net for code review, or #php.doc on Efnet
	* When testing, be sure to add to manual.xml.in in phpdoc/ otherwise it won't be validated/tested/built		* When testing, be sure to add to manual.xml.in in phpdoc/ otherwise it won't be validated/tested/built
		+	* When adding documentation to an already documented extension, the --copy and --phpdoc directives are used to copy only new docs over
		+	* Use --seealso to add skeleton SeeAlso roles, and --example to add skeleton Example roles (and adds a examples.xml).
		+	* Use --test to enter test mode, which affects a few things like when enabled, --copy will print what it would have copied

doc:howto:skeletons

2009-10-02T16:01:54+00:00

1252455273		current
Line 17:		Line 17:
	=== WIP Guides ===		=== WIP Guides ===
	* Guide to [[doc:scratchpad:pecldocs\|documenting a PECL extension]]		* Guide to [[doc:scratchpad:pecldocs\|documenting a PECL extension]]
-	* Guide to [[doc:howto:translations\|Working on a Translation of the PHP Manual]]	+	* Guide to [[translations\|Working on a Translation of the PHP Manual]]

doc:howto:structure

2009-09-09T01:08:51+00:00

	current
Line 1:	Line 1:
	+	==== Knowing the structure ====
	+
	+	The documentation for extensions is located in:
	+
	+	/phpdoc/en/trunk/reference/extension_name/
	+
	+	For example, the SVN extension documentation exists in:
	+
	+	/phpdoc/en/trunk/reference/svn/
	+
	+	There you'll find several files:
	+
	+	* //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)
	+	* //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)
	+	* //examples.xml// (Various examples)
	+	* //foo.xml// (Example, foo can be anything specific to a topic. Just be sure to include via //book.xml//)
	+
	+	A procedural extension (like SVN) also has:
	+
	+	* //reference.xml// (container for the functions, rarely contains any info)
	+	* //functions/// (folder with one XML file per function that the extension declares)
	+
	+	And OO extensions (such as imagick) contain:
	+
	+	* //classname//.xml (container for the methods defined by the class, contains also basic info about it)
	+	* //classname/// (folder with one XML per method that the class declares)
	+
	+	* Note: "//classname//" is the lowercased name of the class, not a literal file or directory name.

doc:howto:translations

2009-11-09T19:04:05+00:00

1252455273		current
Line 13:		Line 13:
	* http://doc.php.net/php/dochowto/chapter-translation.php		* http://doc.php.net/php/dochowto/chapter-translation.php

-	Also, read the [[doc:scratchpad:howto\|HOWTO]] for additional information, like how to download the documentations source from CVS.	+	Also, read the [[doc:howto\|HOWTO]] for additional information, like how to download the documentations source from CVS.

	== Determine if the translation exists, and if it's active ==		== Determine if the translation exists, and if it's active ==