On Oct 11, 2010, at 3:51 AM, Richard Quadling wrote: > 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).
We have a 'unicode' role for this reason, which was going to be used but then the PHP 6 fiasco happened. It's still available though. However, nobody is talking about unicode anymore so I'm not holding my breath despite it being where the web is going (or has gone). > 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. I think it's important for users to be aware of why their code may not work in previous or future versions of PHP. I agree it can get in the way, but think it's worth it (especially if done right). > 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. PHP is a BC friendly language and rarely has drastic changes. I don't think this concern is a big problem. > 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+) Not sure how that would work but it's a rare condition. New features like traits and garbage collection are version specific but over time they won't be. I can't think of any major changes to features except for OOP, and do think we could have handled that better. Syntax changes like if $arr[1,4] exists, or annotations, or foo()[4], those could get tricky. But I'm sure your idea of headings/pages for some features will be useful. > 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. XML attributes are one idea but what it'd generate/do hasn't been investigated. And as someone who thinks knowing the future/past is important, I don't see real value in hiding/moving content based on it. The main use is to have it organized so it'd be easier to deal with both now and well into the future. Regards, Philip
