2.2. Tools on Windows

Although the phpdoc environment is based on many Unix tools and techniques, there are ways to accomplish the same tasks on Windows. It is not too hard to set up a Windows working environment with CVS and the DocBook tools, but put away your mouse as you will need the keyboard for the majority of the tasks! :)

2.2.1. Obtaining the Tools

You need the same tools as on Linux. The very basic thing is a CVS client. You can find one simple command line client here at the CVSHome.org Win32 download pool. We do not recommend GUI tools such as WinCVS, because they can easily screw up the module with files not intended to be there (eg. files with uppercased names). The best is to use one command line client, as this way you are in control.

About XML editors, you are encouraged not to use WYSIWYG XML editors, such as XML Spy, because the often friendly auto-indent, and optimize features can make the XML files so different from the one you started the work with, that the diff posted to our mailing lists and used by translators will be useless. Emacs is also available for Windows if you would like to give it a try ;)

If you want to produce something viewable, or just would like to test the modified file before committing (recommended!), you need some more tools. To get it running on Windows, you'll need these tools:

Note that if you use Cygwin, there is no need to download a CVS client, as Cygwin comes with a CVS client built in.

2.2.2. Installing the Tools

You need to download and install the Cygwin tools. Just select the "Install now!" link and run the supplied setup.exe. It will guide you through the process of installation. These tools are port of standard Unix tools like sed, awk, autoconf, make, perl, ... for Windows.

Note: Be aware, that cygwin is grown to be a very huge project and it includes many programs (such as postgres and apache) ported to Windows, which are not needed for phpdoc. We are unable to give you a list of needed components from cygwin (which you should download and install), because the basic tools are interconnected, and depends on each other. If you manage to find the smallest needed installation, do not hesitate to contact us, and send the solution to us.

Run "Cygwin Bash Shell" command from the Programs menu (it will be added here by the previous step). Now 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.

Warning

Do NOT use symlinks with Cygwin, it's buggy. (Jade doesn't like them, and the shell doesn't handle them very well either)

Change to the dir where your phpdoc snapshot is (or where you want to have it). Use, just like in Windows, the cd command. In Cygwin, the dir command is also supported.

If you don't have your snapshot yet, execute CVS (packaged with Cygwin). More information about CVS can be found in the CVS section of this document.

Make sure that you are in the directory where the phpdoc dir is located. (if you type ls, you should see phpdoc listed). Type mkdir phpdoc-tools, and then unzip Jade to phpdoc-tools/jade.

You also need a working copy of PHP 4.x to build the manual. On Windows, you should put a php.bat file to the phpdoc-tools directory, with a PHP calling line. You may use the recommended php.ini file as the default settings for PHP scripts differ from the ones required by phpdoc PHP scripts. The recommended php.ini file can be found in phpdoc/scripts. Something like this works (modify this according to your PHP setup directory):

@"C:\Program Files\PHP\php.exe" %1 %2 %3 %4 %5 %6 %7 %8 %9

Verify that your directory structure looks like this:

+--phpdoc
|  |
|  +--CVS
|  |
|  +--en
|  |
|  \--...
|
\--phpdoc-tools
   |
   +--jade
   |  |
   |  \--jade.exe (etc)
   |
   \--php.bat

Now go to the phpdoc directory, and execute:

autoconf
./configure --with-lang=your_language_code

Substitute your_language_code with a language code you checked out the files of, and would like to work on. The --with-lang parameter is optional. If you don't specify it, the default is en (English).

If you didn't get any errors, you're ready to rock&roll. Otherwise, you could check out the installation appendix of "DocBook: The Definitive Guide". If you think that the problem is in the build system, ask on the mailing list.