PHP Wiki - doc:howto

communication

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2011/04/06 10:59		current
Line 1:		Line 1:
-	===== Communication =====	+	This page has been removed, in favor of [[http://doc.php.net/tutorial/\|new guide]]
-		+
-	There are four main routes of communication for discussing PHP documentation:	+
-		+
-	* The [[http://php.net/mailing-lists\|phpdoc@lists.php.net]] mailing list	+
-	* The [[http://news.php.net/\|doc-$LANG@lists.php.net]] mailing lists (where $LANG is a lang code)	+
-	* IRC ([[irc://irc.efnet.net/php.doc\|EFnet #php.doc]])	+
-	* Bugs database (http://bugs.php.net)	+
-		+
-	The main mailing list is the main avenue for chat and must be used when discussing major changes to the documentation. It's also used by people wanting to contribute to the project, and really anything related to the PHP documentation.	+
-		+
-	The doc-$LANG lists are dedicated to the translations. They include commit information but also are a place to discuss topics specific to a given translation.	+
-		+
-	IRC is often used when people are collaborating or brain storming for ideas, or for those times when a second set of eyes just seems like a good idea. Of course the mailing list works great for all of this too.	+
-		+
-	The Bugs database is used for, you guessed it, bugs.	+

docbook

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2011/04/06 10:59		current
Line 1:		Line 1:
-	==== Introduction ====	+	This page has been removed, in favor of [[http://doc.php.net/tutorial/\|new guide]]
-		+
-	First, don't be worried about learning another language or syntax because DocBook is fairly straight forward and most contributors simply cut-n-paste existing files, modify the content, then commit. It's just plain text.	+
-		+
-	==== What is DocBook? ====	+
-		+
-	The following is a quote from DocBook: The Definitive Guide:	+
-		+
-	DocBook is a very popular set of tags for describing books, articles, and other prose documents, particularly technical documentation. DocBook is defined using the native DTD syntax of SGML and XML. Like HTML, DocBook is an example of a markup language defined in SGML/XML.	+
-		+
-	Simply this means that writing a DocBook file is no more than writing a text file and using a few simple "tags" when needed. Like HTML, an opening tag is a < bracket followed by the tag's name, optionally some arguments, and then the > bracket (e.g. <para> for paragraphs). A closing tag is a < bracket followed by a / sign, the tag name, then the closing > bracket (e.g. </para> for paragraphs). For example uses, have a look at an existing file within the PHP manual sources, or use the documentation skeletons.	+
-		+
-	As described above, DocBook uses a similar structure to HTML with the main difference being DocBook uses tags to define the meaning whereas HTML often times defines the look and layout. So the idea behind DocBook is to define as much as possible about the information so that build and rendering software will intelligently output the text into many formats.	+
-		+
-	==== Why do we use DocBook? ====	+
-		+
-	We use DocBook because it makes it easy to generate several formats of our documents (HTML, PDF, Microsoft HTML Help (CHM), RTF, etc.), and DocBook is the standard way for storing structured technical information.	+
-		+
-	==== Our DocBook history ====	+
-		+
-	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.	+

editing

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2011/04/17 20:03		current
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 -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!	+

faq

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2013/01/24 03:35		current
Line 1:		Line 1:
-	===== Questions related to writing documentation =====	+	This page has been removed, in favor of [[http://doc.php.net/tutorial/faq.php\|new guide]]
-		+
-	//If a <refentry> should not emit versioning information, what should I do?//	+
-	* Add the role="noversion" to its <refentry>	+
-	* Example: %%<refentry xml:id="reserved.variables.argc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" role="noversion//">%%	+
-		+
-	//How do I add a link to a method?//	+
-	* Use %%<methodname>Class::Method</methodname>%%	+
-	* Note that the case does not matter when adding a link.	+
-		+
-	//How do I add an external link to the documentation?//	+
-	* All external links are added to doc-base/entities/global.ent	+
-	* Add the link there (to global.ent)	+
-	* The global.ent markup might look like: %%<!ENTITY spec.google "http://www.google.com/">%%	+
-	* Add the link to the documentation (foo.xml)	+
-	* The markup might look like: %%<link xlink:href="&spec.google;">google spec</link>%%	+
-	* Be sure the file understands the namespace with %%xmlns:xlink="http://www.w3.org/1999/xlink"%% in the root element	+
-		+
-	//I made a change to a file but want to revert this change, how?//	+
-	* To merge a file to the previous state: svn merge -rHEAD:PREV filename.xml	+
-	* Then, to commit it: svn commit filename.xml -m "reverted previous commit"	+
-		+
-	//I'm about to document a new PHP extension... how should I start?//	+
-	* Use the script found within phpdoc/doc-base/scripts/docgen/*	+
-	* Example: $ php docgen.php -h	+
-	* Example: $ php docgen.php -e simplexml -o outdir	+
-	* It creates the skeletons that you edit then commit	+
-		+
-	//I created skeletons that contain a bunch of default text, should I commit it?//	+
-	* No, edit the files before commit.	+
-	* Reason 1: Translators	+
-	* Reason 2: Temporary often becomes permanent, and bogus text is not good	+
-		+
-	//I documented an extension but it's not building. Why?//	+
-	* Likely because it has not yet been added to doc-base/manual.xml.in	+
-	* So, add the book to the appropriate reference location there. Open file for examples.	+
-	* Or, configure.php is failing... the error should help	+
-		+
-	//I want to contribute to the PHP Manual, how?//	+
-	* First, read the [[doc:HOWTO]]	+
-	* Check out the sources: $ svn checkout http://svn.php.net/repository/phpdoc/modules/doc-en	+
-	* For a translation, change the checkout to phpdoc/modules/doc-{lang} where {lang} is the language code	+
-	* ...	+
-		+
-	//How do I build and/or test the manual locally?//	+
-	* Use phpdoc/configure.php to validate and then [[doc:phd]] to build	+
-	* To validate en: $ php configure.php****	+
-	* To validate fr: $ php configure.php %%--with-lang=fr%% (Change fr to your given language code)	+
-	* To build: $ phd -d .manual.xml****	+
-	* Note: Building is not required, all you must do is check the diff and be sure it validates	+
-		+
-	//Running configure.php ends up Segfaulting, what is up?//	+
-	* There are bugs with certain versions of libxml that cause this, so hacks exist to get around it	+
-	* To execute the hack, pass in: $ php configure.php %%--disable-segfault-error%%****	+
-	* Note: This disables some error checking and beautification but raw errors will be shown	+
-	* Note: Usually the problem is a major XML syntax issue	+
-		+
-	//In the changelog, which order do the PHP versions go?//	+
-	* Newest PHP versions go above the older ones	+
-		+
-	//In the changelog, a change happened in two PHP versions. How do I enter this?//	+
-	* Multiple versions are separated by a comma, with the lesser version first. Example: %%<entry>5.2.11, 5.3.1</entry>%%	+
-		+
-	//How do I add markup for a configure option?//	+
-	* Example: %%<option role="configure">--enable-debug</option>%%	+
-		+
-	//When adding a <note>, should I add a <title>?//	+
-	* Typically titles are useful for notes, but it's not required.	+
-	* Syntax: %%<note><title>foo</title><para>note contents</para></note>%%	+
-		+
-	//A feature became available in PHP X.Y.Z, how do I document that?//	+
-	* Version information for functions is stored inside versions.xml within each extension: phpdoc/en/extname/version.xml	+
-	* Changes to functions, like added parameters, are documented within changelogs for each page	+
-	* Example Text: Feature X has been available since PHP X.Y.Z	+
-	* TODO: Research other ways, and the best way, to write this text (including dealing with code examples)	+
-		+
-	//Why does everyone care so much about whitespace?//	+
-	* See the following article: [[doc:articles:whitespace]]	+
-	* XML is one space, PHP example code is four, and max width is ~78 characters	+
-	* Exceptions: <refpurpose> is on one line, ...	+
-		+
-	//A parameter is optional, how is it documented?//	+
-	* Like normal, except methodparam receives the choice="opt" attribute, and the <initializer> tag is used to signify the default value.	+
-	* Example: %%<methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>false</initializer></methodparam>%%	+
-		+
-	*//Do I need to edit these entities files?//**	+
-	* No, these are auto-generated by the configure process	+
-	* Examples: entities/file-entities.ent and en/reference/foo/entities.bar.xml	+
-	* Also, do not commit them	+
-		+
-	// How do I create a patch? //	+
-	* In the command-line, go to the SVN directory:	+
-	* cd /path/to/phpdoc/svn	+
-	* To diff the entire repository: svn diff****	+
-	* To diff a single file: svn diff foo.xml****	+
-	* Consider piping the diff to a file, so: svn diff foo.xml > mypatch.txt****	+
-		+
-	// How do I apply a patch? //	+
-	* Assuming the file with the patch is named apatch.txt	+
-	* Go to the directory with the files to be patched	+
-	* And run this command: patch -p0 < apatch.txt****	+
-		+
-	// Is there an online editor? //	+
-	* Yes and No.	+
-	* Yes one exists in SVN and is being worked on.	+
-	* No it's not yet in use.	+
-	* Demo: https://edit.php.net/	+
-		+
-	// How often is the documentation built? //	+
-	* Weekly on mirrors, several times daily on the doc server	+
-	* For specifics, see the [[doc:builds\|doc builds]] article	+
-		+
-	// I see example.outputs and example.outputs.similar entities, what's the difference? //	+
-	* The example.outputs.similar entity is used when the output may differ between executions or machines	+
-	* The example.outputs entity output will always, under all conditions, be the same	+
-		+
-	// I need to add a piece of text to three or more pages, how? //	+
-	* Add the snippet to en/language-snippets.ent as an entity	+
-	* Link to the entity within the desired pages	+
-	* This is done so translators can update one version of this text	+
-		+
-	// How do I find missing documentation? Or undocumented (proto only) documentation? //	+
-		+
-	Missing functions (no associated XML files) can be found like so (assuming a doc checkout, and PhD is installed):	+
-	<code shell>	+
-	php doc-base/configure.php	+
-	phd --docbook doc-base/.manual.xml --package PHP --format php	+
-	php doc-base/scripts/check-missing-docs.php -d output/index.sqlite	+
-	</code>	+
-	Undocumented documentation (skeletons exist, but only prototypes and basic information) can be found here: http://doc.php.net/php/undoc_functions.php	+
-		+
-	// What .subversion/config settings should I have set? //	+
-		+
-	<code>	+
-	*.xml = svn:eol-style=native;svn:keywords=Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URL	+
-	</code>	+

gettingstarted

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2013/04/28 10:31		current
Line 1:		Line 1:
-	===== What is needed =====	+	This page has been removed, in favor of [[http://doc.php.net/tutorial/\|new guide]]
-		+
-	==== Joining the PHP Documentation team ====	+
-		+
-	Joining the PHP Documentation team is a simple process, but a process nonetheless. It can be summarized as:	+
-		+
-	== Write the mailing list ==	+
-		+
-	Because official communication is done there, you should [[doc/howto/communication\|write the list]]. Say "Hi" and what you're interested in doing. You may feel more comfortable lurking for awhile, or reading the archives, or hanging out in IRC (#php.doc on Efnet) for awhile, but ultimately let the list know who you are.	+
-		+
-	== Create a doc patch or three ==	+
-		+
-	This shows a few things:	+
-		+
-	* That you really do intend to do some work	+
-	* That you're a real human	+
-	* That you know, for the most part, what you're doing	+
-		+
-	This HOWTO covers how to do this (checkout from SVN, edit, svn diff foo > doc.patch) but ultimately you must do it. We're all in the same boat here, so please jump on board!	+
-		+
-	Or, another (and simpler) way to get started is by using the [[https://edit.php.net/\|Online Documentation Editor]] which allows you to login via facebook/twitter/google connect and write patches.	+
-		+
-	== Talk about the patch ==	+
-		+
-	So now that you've showed initiative enough to actually setup the documentation toolchain, make edits, and create a nice looking patch (or three), it's time to let people know about it. Post it to the mailing list. People will offer feedback and advice, and do remember that we all make mistakes so don't be afraid. The most common mistakes involve whitespace issues so watch that whitespace! :)	+
-		+
-	== Gain commit access ==	+
-		+
-	After talking about the patch, you'll be asked to request a SVN account and soon thereafter it'll be approved with PHP documentation karma granted. In other words, commit your own patches! PHP peer review happens after commits are made, and most committers receive emails regarding each commit and have a look. Essentially, we all trust each other and enjoy seeing each other work.	+
-		+
-	==== Subversion (SVN) ====	+
-		+
-	Since the documentation is stored in SVN, you'll need a SVN client. SVN is a common form of version control and every operating system has clients for this. A client does not mean a GUI although some people prefer GUI interfaces. The following list is not exhaustive put should provide an idea for what we're talking about.	+
-		+
-	== Windows ==	+
-		+
-	The most common is TortoiseSVN. Here are the steps to checkout the sources of the PHP manual using it:	+
-	* Download and install TortoiseSVN: [[http://tortoisesvn.net/]]	+
-	* Open a new explorer window and go to the folder you wish to do the checkout into	+
-	* 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: "https://svn.php.net/repository/phpdoc/modules/doc-en/", then OK to begin the checkout	+
-		+
-	== Mac ==	+
-		+
-	The command-line works fine, download/install the sources (or binaries) from [[http://subversion.tigris.org/]]	+
-		+
-	== Linux ==	+
-		+
-	The command-line works fine, download/install the sources (or binaries) from [[http://subversion.tigris.org/]]	+
-	==== The source files ====	+
-		+
-	//Note:// There are two ways. Everyone should have a local checkout, but the [[https://edit.php.net/\|Online Editor]] also works.	+
-		+
-	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 https://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:	+
-		+
-	* ''cd phpdoc''	+
-	* ''vim en/preface.xml''	+
-	* ''php doc-base/configure.php''	+
-		+
-	In other words, this will create a directory named 'phpdoc' with a subdirectory 'en' that contains all of the English files. And a 'doc-base' directory with files used to validate/build/help the process. Now, a translator will instead do something like the following (to checkout German):	+
-		+
-	* ''svn checkout https://svn.php.net/repository/phpdoc/modules/doc-de phpdoc-de''	+
-	* ''cd phpdoc-de''	+
-	* ''vim de/preface.xml en/preface.xml''	+
-	* ''php doc-base/configure.php %%--%%with-lang=de''	+
-		+
-	Note: The above can all be done anonymously, therefore does not require a SVN account. Going through the above process is required before gaining SVN access, as is submitting a few patches to the [[communication\|phpdoc mailing list]]. After doing so, people realize your're both sane and serious, [[http://php.net/svn-php\|apply for SVN access]] and it will granted so you may commit changes to the PHP documentation yourself.	+
-		+
-	==== PHP ====	+
-		+
-	You'll need a recent version of PHP. Since the build system requires PHP 5.3, you should probably install it. However, building the manual is optional as validation (ensuring XML changes are valid) is a separate process and will work with any version of PHP 5.	+
-		+
-	==== PhD ====	+
-		+
-	The build system that builds both the downloadable and online versions of the PHP manual. It also builds the PEAR manual, and several other DocBook 5 based documents. Installing PhD is optional, however it's recommended so you may see what your changes will look like.	+
-		+
-	Note: doc-base/configure.php is not part of phd. configure.php is what turns all the XML files into one monolithic XML files that phd then processes, therefore, running configure.php before each use of phd is required.	+
-		+
-	==== A text editor ====	+
-		+
-	Any will do, as XML is simply text. Most text editors provide syntax highlighting for XML files.	+
-		+
-	Note: Please disable the 'remove ending whitespace' feature of your text editor.	+

pecldocs

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2014/02/26 15:13		current
Line 1:		Line 1:
-		+	This page has been removed, in favor of [[http://doc.php.net/tutorial/\|new guide]]
-	====Writing PECL Documentation====	+
-		+
-	PECL documentation is stored within the official PHP Manual, and while releasing a PECL extension it's important to publish documentation to allow users to find and know how to use the extension, and easily allow others to contribute to these docs.	+
-		+
-	The process of writing documentation is as follows:	+
-		+
-	* Load the PECL extension into PHP CLI.	+
-	* Checkout the SVN modules, namely phpdoc/en and phpdoc/doc-base. For how, see: [[doc:scratchpad:howto:checkout]]	+
-	* Read the README found within phpdoc for a quick overview of how these docs work	+
-	* Generate the documentation skeletons like so:	+
-		+
-	<code>	+
-	$ cd phpdoc/doc-base/scripts/docgen	+
-	$ php docgen.php --help	+
-	$ php docgen.php --output tmp --extension extname --pecl	+
-	</code>	+
-		+
-	This will create a directory named 'tmp' that will contain documentation skeletons for the 'pecl' extension named 'extname'. Reflection is used to make guesses about the extension, like for classes, methods, functions, constants, parameters, version information, etc. but this information will not be fully correct. Please go through and edit each XML file by updating this information and adding documentation.	+
-		+
-	* Read the Validating Changes section of the [[doc:scratchpad:howto\|PHP Documentation HOWTO]].	+
-	* Once validated, commit this documentation.	+
-		+
-	If the user account lacks phpdoc karma, write the documentation list (phpdoc@lists.php.net) and put in the request. While doing this, show the created documentation and eventually karma will be granted.	+
-	==== What the PECL extension requires ====	+
-	Because docgen utilizes Reflection to create the skeletons, it's necessary for the extensions code to use arginfo structs to provide parameter information.	+
-		+
-	For example, the count() source code has this:	+
-	<code>	+
-	/* Definition of the arginfo */	+
-	ZEND_BEGIN_ARG_INFO_EX(arginfo_count, 0, 0, 1)	+
-	ZEND_ARG_INFO(0, var)	+
-	ZEND_ARG_INFO(0, mode)	+
-	ZEND_END_ARG_INFO()	+
-		+
-	*/ Implement it /*	+
-	zend_function_entry basic_functions[] = {	+
-	PHP_FE(count, arginfo_count),	+
-	{NULL, NULL, NULL}	+
-	};	+
-	</code>	+
-		+
-	Which eventually provides Reflection the information, so:	+
-		+
-	<code>	+
-	$ php --rf count	+
-		+
-	Function [ <internal:standard> function count ] {	+
-		+
-	- Parameters [2] {	+
-	Parameter #0 [ <required> $var ]	+
-	Parameter #1 [ <optional> $mode ]	+
-	}	+
-	}	+
-	</code>	+
-	Need more information? Here's a [[http://cweiske.de/howto/hackingphp5/Hacking.html\|rough draft]] that will one day find itself within the official documentation.	+
-		+
-	==== Other Notes ====	+
-	* Docgen may be used to generate specific documentation too, like for individual classes and functions	+
-	* Write in third person voice (no "You")	+
-	* XML is single spaced	+
-	* Don't commit skeletons and "fill them out later", commit them when they are filled out	+
-	* Skeletons generate several sections that you may not use, such as examples and errors... in this case delete them	+
-	* Don't commit auto-generated files from build time (like entities.*)	+
-	* 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 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	+

skeletons

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2011/04/06 10:59		current
Line 1:		Line 1:
-	==== PHP Documentation Structure and Skeletons ====	+	This page has been removed, in favor of [[http://doc.php.net/tutorial/\|new guide]]
-		+
-	=== Skeletons ===	+
-	* [[doc:skeletons:book\|book.xml]]	+
-	* [[doc:skeletons:configure\|configure.xml]]	+
-	* [[doc:skeletons:constants\|constants.xml]]	+
-	* [[doc:skeletons:examples\|examples.xml]]	+
-	* [[doc:skeletons:function\|function.xml]]	+
-	* [[doc:skeletons:ini\|ini.xml]]	+
-	* [[doc:skeletons:reference\|reference.xml]]	+
-	* [[doc:skeletons:setup\|setup.xml]]	+
-		+
-	=== Structure ===	+
-	* [[doc:skeletons:structure\|File structure]]	+
-	* [[doc:skeletons:oo\|OOP Structure]]	+
-		+
-	=== WIP Guides ===	+
-	* Guide to [[doc:scratchpad:pecldocs\|documenting a PECL extension]]	+
-	* Guide to [[translations\|Working on a Translation of the PHP Manual]]	+
-		+

structure

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2011/04/06 10:59		current
Line 1:		Line 1:
-	==== Knowing the structure ====	+	This page has been removed, in favor of [[http://doc.php.net/tutorial/structure.php\|new guide]]
-		+
-	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.	+

styleguide

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2011/07/10 22:42		current
Line 1:		Line 1:
-	==== Style Guide ====	+	This page has been removed, in favor of [[http://doc.php.net/tutorial/style.php\|new guide]]
-	This style guide affects the PHP Manual.	+
-		+
-	=== Reference ===	+
-	We follow the following style guide as a base:	+
-		+
-	* A first-person active voice is preferred, which also means do not address the reader directly as "You"	+
-	* We follow the [[http://fedoraproject.org/wiki/DocsProject/StyleGuide\|Fedora Style Guide]]	+
-		+
-	=== Conventions specific to the PHP Manual ===	+
-	* The refpurpose should not end with a period	+
-	* Indenting is one space, and never tabs	+
-	* Whitespace changes should never be mixed with content changes	+
-	* Text that's repeated 3x or more should be defined as an entity within language-snippets.ent	+
-	* Many words, such as TRUE, FALSE, and NULL, should use the entity versions instead, like %%&true;%%	+
-	* Using %%<para>%% or %%<simpara>%% does not matter, but %%<para>%% is preferred	+
-	* Constants should be surrounded with %%<constant>%%, like %%<constant>PHP_EOL</constant>%%	+
-	* Functions should be surrounded with %%<function>%%, like %%<function>strlen</function>%% (Or, %%<methodname>%% for methods)	+
-	* Variables should be surrounded with %%<varname>%% like %%<varname>$foo</varname>%%	+
-	* ... Create "common docbook tag usages" instead of repeating....	+
-	* Examples should use the [[http://pear.php.net/manual/en/standards.php\|PEAR Coding Standards]]	+
-		+
-		+
-	=== Common mistakes ===	+
-	* Improper spacing. Mixing tabs with spaces, and indenting	+
-	* Long lines. Line width should not exceed 80 characters, although this is a loose requirement. 100 is probably fine, depending on the situation	+
-	* Committing leftover/bogus text that was generated using scripts/docgen/docgen.php. This should not be committed	+
-	* Windows line endings. Only use Unix line endings	+
-	* Having an IDE or Text editor remove trailing whitespace, then mixing it with commits. Don't do this	+
-	* Mixing %%&example.outputs.similar;%% and %%&example.outputs;%% entities. Use the former when the example output may differ, depending on the users usage/settings	+

translations

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2011/04/06 10:59		current
Line 1:		Line 1:
-	===== Working with Translations =====	+	This page has been removed, in favor of [[http://doc.php.net/tutorial/\|new guide]]
-		+
-	=== Introduction ===	+
-		+
-	The PHP Manual is translated into several languages, but this process requires humans to constantly update each language.	+
-		+
-	=== Getting started ===	+
-		+
-	A few steps must be taken before working on a translation.	+
-		+
-	And since this document is not complete, please read the official HOWTO on this topic:	+
-		+
-	* http://doc.php.net/php/dochowto/chapter-translation.php	+
-		+
-	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 ==	+
-		+
-	This is an easy step for several languages, but not for those that are considered outdated. A few places to look:	+
-		+
-	* Each week a suite of tools are ran against the translations, with the results online here:	+
-	* http://doc.php.net/php/	+
-		+
-	The mailing list. Each translation has its own mailing list that receives both commits and discussion. The lists will show up as php.doc.{lang} below, whereas the mailing address is doc-{lang}@lists.php.net where {lang} is the appropriate country/language code.	+
-		+
-	* http://news.php.net/	+
-		+
-	Several tools/scripts exist within the documentation files that help out finding errors and/or information related to the translation. The output of these scripts are also online:	+
-		+
-	* http://doc.php.net/trantools/	+
-		+
-	=== Write the appropriate mailing list ===	+
-		+
-	Send an email to the translations list and introduce yourself. If you're interested in translating a certain section, say so, or ask for suggestions. While writing this introduction, also send a copy to the main documentation list (phpdoc@lists.php.net).	+
-		+
-	=== Start work on the translation ===	+
-		+
-	The main documentation HOWTO discusses working on the English version, but a few translation specific notes are worth mentioning here:	+
-		+
-	* Add the EN-Revision tag to each translated file.	+
-	* Check out either:	+
-	* phpdoc-all : includes English (phpdoc-all/en/) and every translation (phpdoc-all/{lang}	+
-	* phpdoc-{lang} for the translation, which includes the English version (in en/)	+
-	* Commits go to the translation go to the appropriate list whereas English commits go to doc-cvs@lists.php.net	+

2011/04/06 10:59		current
Line 1:		Line 1:
-	==== PHP Documentation Structure and Skeletons ====	+	This page has been removed, in favor of [[http://doc.php.net/tutorial/\|new guide]]
-		+
-	=== Skeletons ===	+
-	* [[doc:skeletons:book\|book.xml]]	+
-	* [[doc:skeletons:configure\|configure.xml]]	+
-	* [[doc:skeletons:constants\|constants.xml]]	+
-	* [[doc:skeletons:examples\|examples.xml]]	+
-	* [[doc:skeletons:function\|function.xml]]	+
-	* [[doc:skeletons:ini\|ini.xml]]	+
-	* [[doc:skeletons:reference\|reference.xml]]	+
-	* [[doc:skeletons:setup\|setup.xml]]	+
-		+
-	=== Structure ===	+
-	* [[doc:skeletons:structure\|File structure]]	+
-	* [[doc:skeletons:oo\|OOP Structure]]	+
-		+
-	=== WIP Guides ===	+
-	* Guide to [[doc:scratchpad:pecldocs\|documenting a PECL extension]]	+
-	* Guide to [[translations\|Working on a Translation of the PHP Manual]]	+
-		+