mods/phpdoc2/PhpDocumentor/README

   1 $Id: README,v 1.12 2007/09/26 02:57:11 ashnazg Exp $\r
   2 \r
   3 ################################################################################\r
   4                                 phpDocumentor\r
   5 \r
   6 ################################################################################\r
   7 Installation\r
   8 ################################################################################\r
   9 \r
  10 Installation for phpDocumentor is as simple as installing PHP and a web server.\r
  11 If you need help installing a webserver or php, refer to the documentation that\r
  12 comes with the webserver or with php.  phpDocumentor also runs from the \r
  13 command-line, and only requires that PHP CLI version be installed.\r
  14 \r
  15 All users with PEAR should either install this version directly from the \r
  16 package.xml file included in the distribution, or install via \r
  17 "pear install PhpDocumentor."  \r
  18 \r
  19 The command-line interface "phpdoc" will be in the path, you can use it \r
  20 immediately on both windows and unix.  The web interface is in a subdirectory of \r
  21 your document root, be sure to "pear config-set data_dir /path/to/my/htdocs" \r
  22 prior to installation.\r
  23 \r
  24 To use phpDocumentor as a command-line tool in *nix-based systems, simply run \r
  25 the phpdoc script.  In windows, run\r
  26 "c:\php\php.exe phpdoc" where C:\php is the path to the cli version of php.\r
  27 The phpdoc command-line interface will not run with the ISAPI module of PHP.\r
  28 To see the command line options, use phpdoc -h or read at the bottom of this\r
  29 README.\r
  30 \r
  31 There is a BASH shell script that you can put inside your project that can save\r
  32 time writing command-line options of phpdoc. Simply copy makedoc.sh to your\r
  33 project path and edit it. When you wish to rebuild the documentation, run it again. \r
  34 Note that .ini scripts are far easier to edit and are supported via "phpdoc -c file.ini"\r
  35 \r
  36 To use phpDocumentor's web interface, install the files into a subdirectory of\r
  37 your document root (read the webserver's documentation for more information if you\r
  38 don't understand how to install into a subdirectory of your document root).\r
  39 Then, browse to the web page as you would to any other web page.  If you encounter\r
  40 problems, make sure that the web server has write access permissions to the output\r
  41 directory that you choose.  Again, your web server documentation has detailed\r
  42 information on how to do this.  The command-line interface will not have problems\r
  43 with access.\r
  44 \r
  45 If you need more detailed help, check out INSTALL.\r
  46 \r
  47 ################################################################################\r
  48 Release Notes\r
  49 ################################################################################\r
  50 \r
  51 Release notes for the newest version are in Release-1.4.1.\r
  52 \r
  53 1.4.1 is out, a stable release.\r
  54 \r
  55 To learn how to write PHPDoc-style documentation, run phpDocumentor on itself, \r
  56 with ./phpdoc -c makedocs.  Before you do, modify users/makedocs.ini to contain \r
  57 the proper path values.\r
  58 \r
  59 If you find a bug please post it at:\r
  60 http://pear.php.net/bugs/search.php?cmd=display&package_name%5B%5D=PhpDocumentor\r
  61 \r
  62 ################################################################################\r
  63 General Notes\r
  64 ################################################################################\r
  65 phpDocumentor is hosted at phpdoc.org, with downloads and mailing list through \r
  66 sourceforge.net, and primary support at PEAR.\r
  67 \r
  68 webpage:            http://phpdoc.org/\r
  69 documentation:      http://phpdoc.org/manual.php\r
  70 mirror:             http://phpdocu.sourceforge.net\r
  71 projectpage:        http://www.phpdoc.org\r
  72 PEAR:               http://pear.php.net/package/PhpDocumentor\r
  73 \r
  74 For a list of people who have helped work on this project please read the \r
  75 Authors file.\r
  76 \r
  77 phpDocumentor 1.4.1 is released under the LGPL version 2.1, text is in\r
  78 LICENSE.\r
  79 \r
  80 ################################################################################\r
  81 Feature Notes\r
  82 ################################################################################\r
  83 \r
  84 phpDocumentor is a JavaDoc-like automatic documentation generator for PHP,\r
  85 written in PHP.  It is the most versatile tool for documenting PHP.\r
  86 \r
  87 For users new to phpDocumentor, phpDocumentor uses an event-driven parser\r
  88 and intermediary data structures that allow it to perform at a level other\r
  89 automatic documentors for PHP cannot achieve:\r
  90   --parsing any php file, with multiple classes and functions in the same file\r
  91   --fully compliant with even the most esoteric php syntax \r
  92         ($string = <<< EOF, for example)\r
  93   --ability to generate multiple output formats\r
  94   --extremely fast parsing\r
  95   --error/warnings by line number and file to allow for debugging of\r
  96         documentation tags\r
  97   --multiple output templates to easily customize the look of generated\r
  98         documentation\r
  99   --extensive documentation of the package, including a detailed specification\r
 100         for tags and templates\r
 101   --LGPL License\r
 102   \r
 103 New since version 1.3.0:\r
 104   --PHP 5 Parsing\r
 105   --hundreds of bugfixes from version 1.2.3\r
 106 \r
 107 If something is missing from this list make sure sure to file\r
 108 a feature request at PEAR:\r
 109 http://pear.php.net/bugs/search.php?cmd=display&package_name%5B%5D=PhpDocumentor\r
 110 \r
 111 If you want to help code that new feature and get it just right, please let us know.\r
 112 Any help is greatly appreciated, just contact the \r
 113 phpDocumentor team for information on getting started.\r
 114 \r
 115 phpDocumentor needs php 4.1.0 or greater, but you'll see the best performance\r
 116 in the newest version.  The recommended version for phpDocumentor 1.3.0 and up \r
 117 is PHP 5.1.3 or newer.\r
 118 \r
 119 ################################################################################\r
 120 Command Line notes\r
 121 ################################################################################\r
 122 \r
 123 Read the documentation at http://www.phpdoc.org/docs for the most up-to-date\r
 124 command-line information.\r
 125 \r
 126 You can also generate documentation from the source using:\r
 127 \r
 128 phpdoc -c makedocs\r
 129 \r
 130 Run this command from the installation directory, and make sure you have full\r
 131 write and directory creation permissions or it will not work.\r
 132 \r
 133 Generated documentation is accessible via Documentation/new/index.html\r
 134 \r
 135 ################################################################################\r
 136 \r
 137 If you run phpdoc and get :\r
 138 bash: ./phpdoc: No such file or directory\r
 139 \r
 140 Then you haven't installed the cgi version of php.\r
 141 Go to your php src dir and try\r
 142 make clean\r
 143 ./configure\r
 144 make\r
 145 make install\r
 146 \r
 147 phpdoc should work now.\r
 148 \r
 149 If you're using php 4.2.0 or higher you will want to use the cli version\r
 150 instead of the cgi.  Checkout php.net for details on these changes\r
 151 \r
 152 \r
 153 ################################################################################\r
 154 Web Interface notes\r
 155 ################################################################################\r
 156 Put phpdoc.php together with the *.inc files someplace on your webserver.\r
 157 NEVER USE THE WEB INTERFACE ON A PRODUCTION WEBSERVER.  Allowing your server\r
 158 to write files to disk is a serious security risk, and phpDocumentor is not\r
 159 designed to work on insecure systems.  Setup php on a development machine\r
 160 that has a firewall or no internet connection, and run phpDocumentor from there.\r
 161 \r
 162 Make sure your webserver can write to wherever you specify as a target or you\r
 163 will get lots of errors.\r
 164 \r
 165 ################################################################################\r
 166 Thanks\r
 167 ################################################################################\r
 168 Thanks to Sam Blum for his assistance with @example and other enhancements.\r
 169 Thanks to William K. Hardeman for his HTML:Smarty:HandS design.\r
 170 Thanks to Marco von Ballmoos for transforming the HTML:frames converter and\r
 171     templates into a magnificent work of art.\r
 172 Thanks to Andrew Eddie for docbuilder and the CHM Converter enhancements.\r
 173 Thanks to Darren Cook for suggesting exciting new features, and making sure that\r
 174     they worked when implemented.\r
 175 Thanks to Marko Kaening, Dan Convissor for policing the source and finding bugs\r
 176     that would have otherwise gone undetected.\r
 177 Thanks to Juan Pablo Morales for the web interface.\r
 178 Thanks to whoever sent me the patch to make phpDocumentor work better in NT...\r
 179         I have your diff and patched the program but i seem to have lost your name...\r
 180         if you send it to me i'll add it to the Authors file.\r
 181 Thanks to Florian Clever for the newest set of win32 patches... they seem to have\r
 182         fixed the last of the problems.\r
 183     \r
 184     Thanks to EVERYONE who has provided ideas and input, without you,\r
 185                      phpDocumentor would be nothing.\r
 186 \r
 187 ################################################################################\r
 188 ################################################################################\r
 189 If you have any questions please try our mailing list at \r
 190 phpdocu-general@sourceforge.net.\r
 191 \r
 192 joshua eichorn jeichorn@phpdoc.org\r
 193 gregory beaver cellog@php.net\r
 194 chuck burgess ashnazg@php.net\r
 195 \r
 196 \r
 197 \r
 198 vim: set expandtab: \r