On 23 January 2010 07:25, Philip Olson <phi...@roshambo.org> wrote: > Hello everyone, > > What do people think about making PHP 5 a first class citizen? If done, we'd > no longer have phrases like: > > - As of PHP 5 > - Since PHP 5 > - Added in PHP 5 > > Because readers are expected to be using PHP 5. However, I'm against version > (x.X.x) specific manuals for two main reasons: > > - It's a lot of work to maintain > - Knowledge is power, and many write applications to work on a wide array of > minor PHP versions > > And because nobody really uses 5.0.x, we could easily make 5.1.0 the base. > And we could tag the current manual and have it available somewhere, in case > some pour soul really wants it. What do people think?
I've just read through this thread. My one concern is to find a mechanism which is easy to implement for future versions/releases. One day Unicode will be part of PHP and may even become the standard way, with b'strings' becoming a thing of the past, just like PHP4, and u'Strings' becoming just 'Strings'. But Unicode will not be adopted overnight. No more than PHP5 was over PHP4. All those string functions will certainly need to be very clear about the difference between unicode and non-unicode string handling. And the differences between PHP4 and PHP5 have been well documented (by version tags, or inline "since PHPxyx" text). For a user coming to PHP for the first time (hopefully this will always happen), having a manual for THEIR version (whatever it may be) is probably what they would want. Having documentation about dead or unusable features ... sometimes it may be in the way and sometimes it may give impetus to upgrade. The changelog section for functions is great. Having a changelog for non-function usage would be great too, but I think we would need just as many references telling a user who is NOT on the most recent version that the documentation they are reading is not right for them and to look in another section. For significant changes, having headings for each version would seem to be an appropriate way to handle things (for non functions / changelogs). I'd probably suggest only 2 or 3 versions with the remaining versions grouped into a single page or hived off to an archive section when no longer relevant. I'm looking at how Apache and IIS are documented within PHP - 1 page for each significant version (Apache 1.3x, 2.x, IIS 5.1 and 6, IIS 7+) An idea which I'm pretty sure has been mentioned before in this list is to be able to tag chunks/elements in the XML in such a way that when you are editing a page, you see all the history in 1 go. But when the manual is built, the older sections are rendered into an archive section. No need to actually move anything around. Regards, Richard Quadling. -- Richard Quadling Twitter : EE : Zend @RQuadling : e-e.com/M_248814.html : bit.ly/9O8vFY
