Here is the first copy in plain text for initial feedback. It is written as a basic guide to get started with references to the more detailed instructions already available in the howto.
**Quick start for working with the PHP documentation on Windows** Many of the tools used to allow easy authoring of the PHP documentation are built for Linux and so to work with them on Windows it is necessary to emulate a Linux environment. To do this, apart from creating a virtual PC using a tool such as VMWare, the other option is to use a project called Cygwin. This is a Linux command line for Windows. *Initial Setup* 1. Download the Cygwin setup program from http://www.Cygwin.com/setup.exe and run it. 2. Run through the setup process and when asked to select packages, ensure the following are selected: devel/autoconf devel/automake devel/cvs devel/make doc/libxml2 lib/crypt text/openjade Select the "bin" tick box and ensure they are the latest versions. There are many other packages available but are not really needed. These will then download and install. 3. Once installed, you will see a "Cygwin Bash Shell" command in the Programs menu. Running that, you get a command line which behaves same as bash on Unix boxes. If you never worked with bash or Unix before, note that there are slashes (/) instead of backslashes (\) in paths. If you want to access the foo directory on drive c: write it as c:/foo instead of c:\foo. 4. Download and install the latest version of PHP onto your Windows PC if it isn't already there. i.e. not into Cygwin. See the instructions in the PHP manual for details. 5. Assuming you have a php.net CVS account, enter the following command into the Cygwin command prompt to login to the PHP CVS server: cvs -d :pserver:[EMAIL PROTECTED]:/repository login If you get an error about .cvspass not being writable, just execute the command again. The file is automatically created the first time you login. 6. Now, to get the PHP documentation packages, you need to checkout the latest copy of the XML sources from the CVS repository using the following command: cvs -d :pserver:[EMAIL PROTECTED]:/repository checkout phpdoc 7. Now cd to the newly created phpdoc/ directory. 8. Execute the command autoconf There will be no output. It will just return to the command prompt after a short time. 9. Then execute ./configure If you're using a language other than en (English), append --with-lang=codehere For example: ./configure --with-lang=fr If you get an error saying "no PHP binary found" then make sure that your php.exe file is available in your Windows PATH. See http://www.php.net/manual/en/faq.installation.php#faq.installation.addtopath for instructions. Once completed, you will return to the command prompt. *CVS* CVS is used to manage all of the sources and is important to get to grips with. A full guide is available at http://doc.php.net/php/dochowto/chapter-cvs.php *Building the Manual* When you have done some editing, you probably want to see what the changes will look like. This can be done by building the manual sources. This is a simple task of running the command "make" from your phpdoc directory. The build process may take some time, during which HTML will be generated in the phpdoc/html/ directory. There are several formats that can be generated, of which html is the default one. The full list is at http://doc.php.net/php/dochowto/chapter-viewing.php More detailed information about this can be found at http://doc.php.net/php/dochowto/tools-for-xsl.php *Working with the manual* Detailed information about this can be found at http://doc.php.net/php/dochowto/part-working-in-phpdoc.php *Validating XML* It is important to validate the XML you make changes to before committing. There is a script which can do this for you which is called xml-check.php. For example, to use this to check the validity of the en/reference/datetime/functions.xml file, from your phpdoc directory, you would execute: php scripts/xml-check.php en/reference/datetime/functions.xml The output will show any parse errors and output nothing if all is well. More information on this script is available at http://doc.php.net/php/dochowto/scripts.xml-check.php.php *Editors* There are many XML editors available for Windows which can be used to author the XML sources. The ones I have used previously are Macromedia's Dreamweaver and JEdit, with the latter being free from http://www.jedit.org It is important that the editor you choose maintains the formatting and whitespace of the XML documents. *Useful Tools/Links* Notes statistics: http://doc.php.net/php/notes_stats.php Undocumented functions: http://doc.php.net/php/undoc_functions.php http://www.phpdoc.info/meta/phpsrc-vs-phpdoc.php Functions with missing examples: http://doc.php.net/php/missing_examples.php Translation files up to date: http://doc.php.net/php/revcheck.php Open documentation bugs: http://bugs.php.net/search.php?boolean=0&limit=All&order_by=status&direction=ASC&cmd=display&status=Open&bug_type%5B%5D=Documentation+problem&bug_age=0 Function aliases: http://www.phpdoc.info/meta/function-aliases.php phpdoc mailing list archive: http://marc.theaimsgroup.com/?l=phpdoc -- David Mytton http://www.olate.co.uk
