jeroen Wed May 16 14:31:34 2001 EDT
Modified files:
/phpdoc README.win32
Log:
Fool proof version.
If you're capable of writing documentation, you
should now be able to get it running with M$ without
ever having to wonder what SGML etc is.
XSL things have been removed
changed linebreakes to win32 ones, for those not
using a real text-editor, but someting like notepad
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 $
