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