$Id: README,v 1.41.2.4 2002/11/07 21:56:10 CelloG Exp $

################################################################################
				phpDocumentor

################################################################################
Installation
################################################################################

Installation for phpDocumentor is as simple as installing PHP and a web server.
If you need help installing a webserver or php, refer to the documentation that
comes with the webserver or with php.

To use phpDocumentor as a command-line
tool in *nix-based systems, simply run the phpdoc script.  In windows, run
"c:\php\php.exe phpdoc" where C:\php is the path to the cgi version of php.
The phpdoc command-line interface will not run with the ISAPI module of PHP.
To see the command line options, use phpdoc -h or read at the bottom of this
README.

There is a BASH shell script that you can put inside your project that can save
time writing command-line options of phpdoc. Simply copy makedoc.sh to your
project path and edit it. When you wish to rebuild the documentation, run it again. 

To use phpDocumentor's web interface, install the files into a subdirectory of
your document root (read the webserver's documentation for more information if you
don't understand how to install into a subdirectory of your document root).
Then, browse to the web page as you would to any other web page.  If you encounter
problems, make sure that the web server has write access permissions to the output
directory that you choose.  Again, your web server documentation has detailed
information on how to do this.  The command-line interface will not have problems
with access.

If you need more detailed help, check out INSTALL

################################################################################
Release Notes
################################################################################

Release notes for the newest version are in Release-1.1.0

1.1.0 is out, a FINAL release

To learn howto write PHPDoc-style documentation checkout spec/howto.html
A detailed reference is in the spec/index.html.

If you find a bug please post it at:
http://sourceforge.net/tracker/?func=add&group_id=11194&atid=111194

################################################################################
General Notes
################################################################################
phpDocumentor is hosted at phpdoc.org, with downloads and mailing list through 
sourceforge.net

webpage: 	http://phpdoc.org/
mirror: 	http://phpdocu.sourceforge.net
projectpage: 	http://sourceforge.net/projects/phpdocu

For a list of people who have helped work on this project please read the 
Authors file

phpDocumentor is released under the GPL the text of the license is in COPYING

################################################################################
Feature Notes
################################################################################

phpDocumentor is a JavaDoc-like automatic documentation generator for PHP
written in PHP.  It is the most versatile tool for documenting PHP.

For users new to phpDocumentor, phpDocumentor uses an event-driven parser
and intermediary data structures that allow it to perform at a level other
automatic documentors for PHP cannot achieve:
  --parsing any php file, with multiple classes and functions in the same file
  --fully compliant with even the most esoteric php syntax 
  	($string = <<< EOF, for example)
  --ability to generate multiple output formats
  --extremely fast parsing
  --error/warnings by line number and file to allow for debugging of
	documentation tags
  --multiple output templates to easily customize the look of generated
	documentation
  --extensive documentation of the package, including a detailed specification
	for tags and templates
  --open source, GPL
  
New in version 1.1:
  --new template for the default HTML Converter, phphtmllib.  This template courtesy of
    Walter Boring IV (http://phphtmllib.newsblob.com/)
  --3 new converters (PDF:default, CHM:default, and HTML:Smarty)
  --NEW COMMAND-LINE SYNTAX -o format:convertername:template (like PDF:default:default
    or HTML:default:DOM/l0l33t)
  --25% faster than version 1.0! bugfixes and rewriting of recursive code did the trick
  --fully reworked Converter code makes it much easier to write a Converter
  --documents global variables and their usage in functions
  --documents static variables in functions
  --documents CVS roots directly
  --much more stable than 1.0
  --automatic linking to elements in any documented package, and a new
    package-override for linking packagename#elementname
  --shell script contributed by Roberto Berto simplifies documenting
  --"Powered by phpDocumentor" image available for use on websites that display docs
    created by phpDocumentor

If something is missing from this list make sure sure to file
a feature request on sourceforge

http://sourceforge.net/tracker/?func=add&group_id=11194&atid=361194

If you want to help code that new feature and get it just right, please let us know.
Any help is greatly appreciated, just contact the 
phpDocumentor team for information on getting started.

phpDocumentor needs php 4.1.0 or greater, but you'll see the best performance
in the newest version.  The recommended version for 1.1.0 is 4.2.0+.

################################################################################
Command Line notes
################################################################################
 -o     --output	        output information, format:converter:template (HTML:default:DOM\l0l33t for example)
 
 -ct	--customtags	        comma-separated list of non-standard @tags to pass to the converter as valid tags

 -d     --directory             name of a directory(s) to parse directory1,directory2

 -dh	--hidden                set equal to on (-dh on) to descend into hidden directories
			       	        (directories starting with '.'), default is off

 -dn	--defaultpackagename	name to use for the default package.  If not specified, uses 'default'

 -f     --filename              name of file(s) to parse ',' file1,file2.  Can contain complete path and * ? wildcards
 
 -i	--ignore	        file(s) that will be ignored multiple separated by ','.  Wildcards * and ? are ok
 
 -q	--quiet          	do not be verbose

 -pp	--parseprivate  	parse elements marked private with @access.  Use on/off, default off

 -po	--packageoutput 	output documentation only for selected packages.  Use a comma-delimited list

 -t	--target              	path where to save the generated files

 -ti	--title         	title of generated documentation, default is 'Generated Documentation'
 
 -j	--javadocdesc		JavaDoc-compliant short desc parsing, uses everything up to the first . as the summary,
 				        and the whole thing as the long description

You can have multiple directories and multiple files, as well as a combination of both options

################################################################################

if you run phpdoc and get :
bash: ./phpdoc: No such file or directory

Then you haven't installed the cgi version of php
goto your php src dir and try
make clean
./configure
make
make install

phpdoc should work now

If your using php 4.2.0 or higher you might want to make the cli version
instead of the cgi.  Checkout php.net for details on these changes


################################################################################
Web Interface notes
################################################################################
Put phpdoc.php together with the *.inc files someplace on your webserver.
NEVER USE THE WEB INTERFACE ON A PRODUCTION WEBSERVER.  Allowing your server
to write files to disk is a serious security risk, and phpDocumentor is not
designed to work on insecure systems.  Setup php on a development machine
that has a firewall or no internet connection, and run phpDocumentor from there.

Make sure you webserver can write to where ever you specify as a target or you
will get lots of errors

################################################################################
Thanks
################################################################################
Thanks to Gregory Beaver for all his work on adding features and fixing bugs
	without him it would have taken a lot longer to get where we are now.
Thanks to Juan Pablo Morales for the web interface.
Thanks to whoever sent me the patch to make phpdocumentor work better in NT
	I have your diff and patched the program but i seem to have lost your
	name if you send it to me i'll add it to the Authors file
Thanks to Florian Clever for the newest set of win32 patches they seem to have
	fixed the last of the problems.

################################################################################
################################################################################
if you have any questions please email me
joshua eichorn jeichorn@phpdoc.org
gregory beaver cellog@users.sourceforge.net




vim: set expandtab: 
