Index: phpdoc/README.win32 diff -u phpdoc/README.win32:1.3 phpdoc/README.win32:1.4 --- phpdoc/README.win32:1.3 Tue May 15 11:55:14 2001 +++ phpdoc/README.win32 Wed May 16 14:31:34 2001 @@ -1,121 +1,151 @@ -THIS README FILE CONTAINS WIN32 SPECIFIC NOTES FOR BUILDING PHP -DOCUMENTATION. FOR GENERAL INFO SEE README FILE IN SAME DIRECTORY. - -READ THIS FIRST - - This directory contains source files and a setup for converting - PHP's XML documentation into presentation formats like HTML and - RTF. You should not have to bother with this unless you are - writing documentation yourself, or if you simply are curious about - how the XML stuff works. - - If you just want to read the documentation, download it from - http://www.php.net/docs.php - -INTRODUCTION - - All the documentation is written with XML using the DocBook - DTD. See: - - http://www.oasis-open.org/docbook/ - - If you want to produce something viewable, you need Jade and - Norman Walsh's modular DocBook stylesheets. See: - - http://www.jclark.com/jade/ - http://nwalsh.com/docbook/dsssl/ - - There is a Reference for DocBook at - - http://www.oasis-open.org/docbook/documentation/reference/ - - - Most major linux distributions should already come with ready to use - packages. This is not case for Windows. You must do following steps: - - 1. Download and unpack the distributions of - - Jade, - - DSSSL stylesheets - - 2. Download ISO entity sets (http://www.oasis-open.org/cover/ISOEnts.zip) - and unzip them into some directory, for example c:\isoent. Create file - named isoent.cat in this directory and place following code into it: - -PUBLIC "ISO 8879:1986//ENTITIES Diacritical Marks//EN" "isodia" -PUBLIC "ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN""isonum" -PUBLIC "ISO 8879:1986//ENTITIES Publishing//EN" "isopub" -PUBLIC "ISO 8879:1986//ENTITIES General Technical//EN" "isotech" -PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN" "isolat1" -PUBLIC "ISO 8879:1986//ENTITIES Added Latin 2//EN" "isolat2" -PUBLIC "ISO 8879:1986//ENTITIES Greek Letters//EN" "isogrk1" -PUBLIC "ISO 8879:1986//ENTITIES Monotoniko Greek//EN" "isogrk2" -PUBLIC "ISO 8879:1986//ENTITIES Greek Symbols//EN" "isogrk3" -PUBLIC "ISO 8879:1986//ENTITIES Alternative Greek Symbols//EN" "isogrk4" -PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN" "isoamsa" -PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Binary Operators//EN" "isoamsb" -PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Delimiters//EN" "isoamsc" -PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Negated Relations//EN" "isoamsn" -PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Ordinary//EN" "isoamso" -PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Relations//EN" "isoamsr" -PUBLIC "ISO 8879:1986//ENTITIES Box and Line Drawing//EN" "isobox" -PUBLIC "ISO 8879:1986//ENTITIES Russian Cyrillic//EN" "isocyr1" -PUBLIC "ISO 8879:1986//ENTITIES Non-Russian Cyrillic//EN" "isocyr2" - - 3. Directory where jade.exe is located must be added into your - PATH environment variable. - - 4. Make the catalog files available. - Set the environemt variable SGML_CATALOG_FILES, e.g.: - SGML_CATALOG_FILES=c:/jade/catalog;c:/isoent/isoent.cat - - 5. You need to download and install cygwin tools from www.cygwin.com. - Just select "Install now!" link and run supplied setup.exe. It - will guide you through process of installation. - - These tools are port of standard unix tools like sed, awk, - autoconf, make, perl, ... for Windows. - - 6. If you want to build documentation just run "Cygwin Bash Shell" - command from Programs menu (it will be added here by previous - step). - - 7. Now you get a command line which behaves same as bash on unix - boxes. Change to directory where you have snapshot of phpdoc. - (If you haven't snapshot yet, use CVS command as described on - http://www.php.net/cvs-php.php. CVS is part of cygwin, so you - do not need to download additional piece of software). - - If you never worked with bash or unix machine before, note that - there are used slashes (/) instead of backslashes (\) in - paths. If you want access directory foo on drive c: write - is as c:/foo instead of c:\foo. - - 8. Now do same steps as on unix machine. For example for building - HTML version of documentation use: - - autoconf - ./configure --with-dsssl=c:/path/to/dsssl/stylesheets/dir - make html - - to make your local language, replace the above configure-command with - - ./configure --with-dsssl=c:/path/to/dsssl/stylesheets/dir --with-lang=xx - - for further options, simply type - ./configure --help - - 9. Wait a few minutes (now it is time to have a couple of tea or - explore bash functionality in another window - it is really - funny having "old good unix commands" on Windows box ;). - - If you have a problem with building the PHP Documentation: - - Consult the DocBook Installation Guide and check what you're missing at - http://www.oasis-open.org/docbook/documentation/reference/html/appa.html - - -Based on README -Win32 specific notes added by Jirka Kosek email protected>> - and Thomas email protected>> - -Last modified $Date: 2001/05/15 18:55:14 $ +THIS README FILE CONTAINS WIN32 SPECIFIC NOTES FOR BUILDING PHP +DOCUMENTATION. FOR GENERAL INFO SEE README FILE IN SAME DIRECTORY. + +READ THIS FIRST + + This directory contains source files and a setup for converting + PHP's XML documentation into presentation formats like HTML and + RTF. You should not have to bother with this unless you are + writing documentation yourself, or if you simply are curious about + how the XML stuff works. + + If you just want to read the documentation, download it from + http://www.php.net/docs.php + +INTRODUCTION + + All the documentation is written with XML using the DocBook + DTD. See: + + http://www.oasis-open.org/docbook/ + + The one and only purpose of this readme is to get your win32- + machine creating the manual in various formats from the xml- + sources. If you want to know how docbook etc works, don't + pay too much attention to this document. That's not where + the phpdoc-team is for. + + If you want to produce something viewable, you need some tools. + To get it running with windows, you'll need these tools: + + Cygwin (bash for windows; it's huge...) + http://www.cygwin.com/ + + Jade (the actual parser, take the windows binary dist) + http://www.jclark.com/jade/ + + Norman Walsh's modular DocBook stylesheets: + http://nwalsh.com/docbook/dsssl/ + + Some ISO-entity declarations: + http://www.a-es2.uu.nl/~jeroen/iso-entities.zip + + + There is a Reference for DocBook at: + http://www.oasis-open.org/docbook/documentation/reference/ + +STEP BY STEP INSTALLATION + + Most major linux distributions should already come with + ready to use packages. This is not case for Windows. You must do + following steps: + + 1. You need to download and install cygwin tools. + Just select "Install now!" link and run supplied setup.exe. It + will guide you through process of installation. + + These tools are port of standard unix tools like sed, awk, + autoconf, make, perl, ... for Windows. + + 2. Run "Cygwin Bash Shell" command from Programs menu (it will be + added here by previous step). + + 3. Now you get command line which behaves same as bash on unix + boxes. Change to directory where you have snapshot of phpdoc. + (If you haven't snapshot yet, use CVS command as described on + http://www.php.net/cvs-php.php. CVS is part of cygwin, so you + do not need to download additional piece of software). + + If you never worked with bash or unix machine before, note that + there are used slashes (/) instead of backslashes (\) in + paths. If you want access directory foo on drive c: write + is as c:/foo instead of c:\foo. + + NOTE: do NOT use symlinks with cygwin, it's buggy. (jade doesn't + like them, and the shell doesn't handle them very well either :( ) + + 4. Change to the dir where your phpdoc snapshot is (or where you + want to have it). Use, just like windows, the 'cd' command. + In cygwin, the 'dir'-command is also supported. + + 5. If you don't have your snapshot yet, execute cvs (packaged with + cygwin) as described on http://www.php.net/anoncvs.php + Type 'man cvs' to get help for cvs. (this is a so-called man-page) + + Note: if you decide to use another directory in one of the next + steps, you'll probably need to modify phpdoc/configure.in manually. + We do not give any support if you're self-opinionated :) + Currently you can only specify the dsssl location manually + by using the --with-dsssl=C:/path/to/dsssl option with configure. + + 6. Make sure that you're in the directory where the phpdoc-dir + is located. (if you type 'ls', you should see 'phpdoc' listed.) + + 7. Type mkdir phpdoc-tools, and then unzip: + - jade to phpdoc-tools/jade, + - Norman Welsh' DSSSL's to phpdoc-tools/dsssl/docbook and + - the ISO-entities to phpdoc-tools/iso-entities. + + 8. Verify that your directorystructure looks like this: + + +--phpdoc + | | + | +--CVS + | | + | +--en + | | + | +--etc... + | + +--phpdoc-tools + | + +--dsssl + | | + | +--docbook (with docbook.dcl etc) + | + +--iso-entities (with ISOamsa etc) + | + +--jade (with jade.exe etc) + + + 9. Now go to the phpdoc directory, and execute: + + autoconf + ./configure [--with-lang=nl] # defaults to 'en' + + 10. If you didn't get any errors, you're ready to rock&roll. + Otherwise, you could check out: + + http://www.oasis-open.org/docbook/documentation/reference/html/appa.html + +GENERATING THE MANUAL + + To compile a manual from the + xml-sources, execute one of the following in your phpdoc + directory: + + make html # creates html-files + make bightml # creates one large html-file + make pdf # adobe's pdf + make rtf # Rich text (ms word) + make dvi # Device Independent file + make ps # postscript + + + This can take a while, 'make html' takes exactly 8 minutes on a + 1GHz Pentium with 128MB RAM, running Windows 2000. + +Based on README, Win32 specific notes added by Jirka Kosek email protected>> +Made fool&fail proof (hopefully) by Jeroen van Wolffelaar email protected>> + + +Last modified $Date: 2001/05/16 21:31:34 $