1$Id: Release-1.2.0rc1 234145 2007-04-19 20:20:57Z ashnazg $ 2 3PhpDocumentor Version 1.2.0 RELEASE CANDIDATE 1 4################################################################################ 5http://www.phpdoc.org 6Joshua Eichorn jeichorn@phpdoc.org 7Gregory Beaver cellog@php.net 8################################################################################ 9################################################################################ 10 11The phpDocumentor team would like to announce the release of phpDocumentor 121.2.0 RELEASE CANDIDATE 1. All features that will be present in the final 13release of 1.2.0 have been implemented, and all known bugs fixed. This release 14is only intended to ensure that all bugs have been fixed before the big release. 15 16The structure of the {@source} tag has changed slightly in this release. See 17the documentation of inline {@source} for details 18 19for PEAR users, the new --pear command-line switch will be a boon. Leave it on 20by default if your package follows PEAR coding and directory naming standards 21 22The peardoc2 converter has been moved to an extension of the DocBook converter, 23to use, the command-line has changed from XML:DocBook:peardoc2 to 24XML:DocBook/peardoc2:default. 25 26------ 27IMPORTANT: phpDocumentor 1.2.0rc1 requires PHP version 4.1.0 or greater. 28phpDocumentor will function best with PHP version 4.3.0 or greater, as it will 29use of the tokenizer extension if php 4.3.0 is installed for a tremendous 30increase in parsing speed. 31------ 32 33phpDocumentor is a JavaDoc-like automatic documentation generator for PHP 34written in PHP. It is the most versatile tool for documenting PHP. 35 36Once again, phpDocumentor brings a great increase in usability with the 1.2 37branch. The addition of a tokenizer-based parser increases parsing speed by 38up to 4 times (that's 400% faster) compared to previous versions. In addition, 39scalability has been improved, allowing generation of documents in multiple 40output formats with one command. The usage of config files makes repetitive 41parsing tasks straightforward and reduces the chance for error. 42 43The addition of DocBlock templates, extended documentation (tutorials) parsing, 44and many other new features make this release the most useful automatic 45documentor for any programming language. 46 47The default HTML Converter has been ported to a new Smarty-based converter, 48HTMLframesConverter, and all of the old templates have been ported to the new 49Smarty-based format. The HTMLdefaultConverter has been deprecated since its 50functionality is redundant. Due to the time it takes to convert a template to 51the new format, the phpDocumentor team extends an offer to do this conversion 52for anyone who has a brand new template. We may also include the template in a 53future release, if permission is granted. 54 55Due to interest from PEAR programmers, there is a new beta-quality XML:DocBook 56converter with peardoc2 templates. This converter could also generate other 57DocBook formats, if desired, but does not generate indexing for this release. 58 59The PDF Converter has stepped up to beta-quality, is fully templatable, and 60has most bugs completely fixed. The CHM converter has also taken major strides 61and is close to beta quality. 62 63As predicted, the Smarty template engine is the primary template engine for 64all converters. 65 66For users new to phpDocumentor, phpDocumentor uses an event-driven parser 67and intermediary data structures that allow it to perform at a level other 68automatic documentors for PHP cannot achieve: 69 --parsing any php file, with multiple classes and functions in the same file 70 --fully compliant with even the most esoteric php syntax 71 ($string = <<< EOF, for example) 72 --ability to generate multiple output formats 73 --extremely fast parsing 74 --error/warnings by line number and file to allow for debugging of 75 documentation tags 76 --multiple output templates to easily customize the look of generated 77 documentation 78 --extensive documentation of the package, including a detailed specification 79 for tags and the included template engine 80 --open source, GPL 81 82 83A full listing of all closed bugs and feature requests can be found in the 84next section of the notes 85 86phpDocumentor 1.2.0rc1 is nearly ready for production use documenting any PHP 87project, download it and try the most advanced solution for PHP documentation 88today to help us find the last hidden bugs. 89 90################################################################################ 91 92The following bugs are fixed in version 1.2.0RC1 93 [ 566663 ] @param &$arg broken 94 [ 657041 ] {@source} doesn't work right 95 [ 675871 ] --pear breaks if not a pear repository 96 [ 678176 ] Inherited vars/methods in HTML:frames:phpedit 97 [ 680652 ] Optional method/function parameters 98 [ 681459 ] {@internal}} not quite working 99 [ 681463 ] {@source} drops characters 100 [ 681735 ] {@source} in sdesc needs warning 101 [ 682490 ] {@internal}} not parsed right by highlightparser 102 [ 682491 ] multi-line description fubared in @tag 103 [ 687091 ] special characters not encoded 104 [ 687364 ] highlightparser $class->member incorrect 105 [ 687403 ] {@source} leaves "}" 106 [ 689874 ] is_a is not avaliable in PHP 4.1.0 107 [ 689893 ] Warnings on PHP 4.1.0 108 [ 689894 ] getincludevalue() missing argument 2 warning 109 [ 692522 ] @uses is screwy 110 [ 693213 ] tutorials post-processed twice 111 [ 693215 ] {@internal}} on single line not working 112 [ 694448 ] PKZip has bug, use winzip (not phpDocumentor bug) 113 [ 694594 ] PEAR mode: destructor image not shown by phpedit template 114 [ 694742 ] PDF converter has no table of contents 115 [ 695291 ] link to todo disappears in HTML:Smarty:* 116 [ 695482 ] @uses not checking for @access private 117 [ 695622 ] HTML:Smarty:* has no package-level docs 118 [ 696883 ] <code> in description crashes parser 119 [ 697156 ] PHP Warning with PDF Converter 120 [ 697656 ] putting a <code> inside a <li> turns it into a literal 121 [ 698417 ] {@link element descrip} wrong 122 [ 697644 ] parse fails if unmatched html tag, or text outside <li> list 123 [ 698468 ] Fatal error when inline tag across two lines 124 [ 698356 ] {@internal} not working properly 125 [ 701199 ] extra br in @filesource generation 126 [ 702549 ] --quiet option not valid? 127 [ 705897 ] HTML:frames:earthli misses Page.gif 128 [ 708560 ] intelligent list handling isn't quite working 129 [ 708559 ] @category tag not really working 130 [ 710366 ] <i>-Tag is ignored 131 [ 710700 ] empty defaultpackagename = caused busy loop 132 [ 711569 ] Fatal Error: Undefined Method during write 133 [ 712704 ] HTML:Smarty:* drops class level author information 134 [ 708914 ] <var>, <samp>, <kbd> broken 135 [ 713201 ] variable variables are not parsed properly in @global 136 [ 713954 ] @param type $var when &$var broken 137 [ 715077 ] HighlightParser needs @tag object classname support 138 [ 715084 ] HighlightParser craps out after $var-> 139 [ 715452 ] @example doesn't work with anything other than .php 140 [ 718253 ] Using 'parent' in @example file causes crash 141 142The following bugs are fixed in version 1.2.0BETA3 143 [ 661317 ] PDF converter in subpackage ids broken 144 [ 669945 ] CHM: "undefined function: convert()" with multiple outputs 145 [ 670205 ] inherited methods have no links 146 [ 670341 ] <pre> in docblock doesn't htmlentitie 147 [ 670350 ] left_frame.tpl missing package level doc link 148 [ 670440 ] Io::getBase() is buggy 149 [ 670903 ] inline desc <code> not <pre>-ized 150 [ 671620 ] warning in Parser line 2271 151 [ 672149 ] @desc broken 152 [ 674053 ] Support for require_once 153 [ 674059 ] requires PHP version 4.2 or higher 154 [ 674075 ] Bad @param kills parser 155 [ 677105 ] unbalanced HTML-comments in output of HTML:frames:phpedit 156 [ 677821 ] define not parsed right in highlightparser 157 [ 677822 ] {@source} not showing whole source 158 [ 677826 ] nonsense @link in @see breaks HTML output 159 [ 677938 ] whitespace wrong after certain docblocks 160 161The following bugs are fixed in version 1.2.0BETA2 162 [ 665707 ] Warnings and errors in new_phpdoc.php 163 [ 666307 ] whitespace not ignored in @param 164 [ 669132 ] "no @package tag was used" error but @ignore & @package used 165 [ 669525 ] {$children[kids].sdesc} contains parent sdesc 166 [ 669613 ] Call to undefined function: getclassleft() 167 [ 669615 ] methods disapper 168 [ 669640 ] javadocdesc broken 169 [ 669909 ] PDF text starts off left side of page when have package.html 170 171The following bugs are fixed in version 1.2.0BETA1a 172 [ 661976 ] @see broken 173 [ 662630 ] {} delimited variables within strings mess up the parser 174 [ 663435 ] define values, global variable values need htmlentities 175 [ 664058 ] @param not displayed in HTMLframesConverter 176 177The following bugs are fixed in version 1.2.0BETA1 178 179 [ 586357 ] ignore a directory 180 [ 637921 ] sorting is weird with multiple package 181 [ 637928 ] multiple converters legal, but fails 182 [ 638042 ] two declarations of checkstate() 183 [ 638128 ] commandline win32 fails, w/relative path 184 [ 639553 ] new_phpdoc.php fails with php 4.2.3 185 [ 640507 ] constructor links broken 186 [ 641076 ] second instance of loop fails 187 [ 641235 ] need trim of -f and -d commandline 188 [ 641334 ] parse <script language="php"> as <?php 189 [ 642427 ] Incorrect Anchor link from elementIndex 190 [ 645588 ] elements named "function.." or "global.." don't link 191 [ 646281 ] {@link mailto:e@a descrip} broken 192 [ 647494 ] {@link element1, element2} incorrect 193 [ 648684 ] links to global vars, defines in Smarty wrong 194 [ 649646 ] comments not parsed in function 195 [ 649953 ] phpdoc command-line only runs from install dir 196 [ 650946 ] link to phpdoc.org new window 197 [ 651837 ] getLink broken in rare case 198 [ 653627 ] @staticvar broken 199 [ 654429 ] tutorial prev/next links not working 200 [ 655372 ] smarty template not found in pdf convers 201 [ 657041 ] {@source} doesn't work right 202 [ 657387 ] parent/child tutorials converted twice 203 [ 657726 ] used by link htmlentitiezed 204 [ 657739 ] need separate categories of {@tags} 205 [ 657934 ] subtrees not processed in Converter 206 [ 658120 ] PDF define template has bug 207 [ 658121 ] PDF Converter not passing elements sorte 208 [ 661316 ] @tutorial tutorial.ext#subsection.section broken 209 210There of course were other small bugs fixed, these were just the bugs with 211entries in source forge. You can view the bug details or reopen it if 212you think it's not totally fixed at: 213http://sourceforge.net/tracker/?group_id=11194&atid=111194 214 215Features added that had Feature Request entries in SF for 1.2.0 rc 1: 216 [ 681470 ] Add syntax highlighting for <programlisting role="php"> 217 [ 682810 ] Xref 218 [ 683101 ] starting/ending line numbers of docblocks/classes/methods 219 [ 687366 ] phpEdit-style list support 220 [ 695621 ] link to section of @filesource from each element 221 [ 714025 ] @license tag 222 223Features added that had Feature Request entries in SF for 1.2.0 beta 3: 224 [ 674470 ] output a list of all @todos 225 [ 675194 ] -cp for converter-specific dynamic params 226 227Features added that had Feature Request entries in SF for 1.2.0 beta 2: 228 [ 650251 ] @filesource tag 229 [ 670184 ] @example tag 230 [ 670189 ] @internal/{@internal}} 231 [ 670190 ] --ignore-tags command-line 232 233Features added that had Feature Request entries in SF for 1.2.0 beta 1a: 234 [ 663436 ] --title available in all pages, html 235 [ 663437 ] error if @package is missing 236 [ 663439 ] PEAR command-line switch 237 238Features added that had Feature Request entries in SF for 1.2.0 beta 1: 239 240 [ 541896 ] Create an Extended Howto 241 [ 558118 ] add {@inheritDoc} 242 [ 562604 ] Using @access blocs (_start ... _end) 243 [ 564991 ] auto-links to php manual 244 [ 566942 ] add {@link seeelement descrip} 245 [ 569746 ] make Program_root/ template thing 246 [ 577714 ] have master directory option 247 [ 586401 ] @access protected 248 [ 608603 ] REQUEST:class/function usage information 249 [ 615419 ] manuals like "php.net manual" 250 [ 623055 ] Zend IDE suport 251 [ 634518 ] inherit @author, @version, @copyright 252 [ 634589 ] @uses element 253 [ 634641 ] A way to document form variables 254 [ 635184 ] update all templates to phphtmllib 255 [ 637409 ] {keyword} - {data} pairs not flexible 256 [ 637660 ] parse type|type 257 [ 637920 ] simple way to extend a converter 258 [ 642235 ] Index of phphtmllib template 259 [ 645775 ] line numbers for elements 260 [ 651275 ] tutorials 261 [ 651716 ] automatically find README/INSTALL 262 [ 651723 ] @tutorial/{@tutorial} 263 [ 653608 ] allow the /user ini dir to be configable 264 265################################################################################ 266 267The documentation has been updated for this release you can view it at 268http://phpdocu.sourceforge.net/spec/ 269or in the distribution in the spec directory 270 271The changelog is available in the tarball, or online at 272http://phpdocu.sourceforge.net/Changelog 273 274You can download the newest version from 275http://phpdocu.sourceforge.net/downloads.php 276 277And of course you can reach the webpage at http://phpdocu.sourceforge.net/ or 278http://phpdoc.org/ 279 280enjoy 281-joshua eichorn <jeichorn@phpdoc.org> 282-gregory beaver <cellog@php.net> 283 284 285vim: set expandtab : 286