Re: Proposal of removing PHP4 references from the manual

On 15 July 2014 04:28, Philip Olson <philip@roshambo.org> wrote: > Hello everyone, > > To summarize this thread the best I can, along with inserting my > own opinions on the matter, it sounds like the easy parts are: > > * Create a snapshot of the current PHP Manual, but only the > downloadable versions with "php4" in the filenames, and > with related "this is a snapshot!" text in the manual itself > The current PHP Manual has had a number of PHP 4-specific things already removed entirely, as we've discussed. While a current snapshot would create a clear line in the sand, it's missing chunks that I think people will be looking for. I'd prefer that we take the time to provide a useful archive by, for example, re-instating the removed extensions (e.g. domxml). Not that anyone has suggested this, but I don't think we can realistically remove everything PHP 5-related to leave a PHP 4 manual (or, can we?). > * Create an /archives/ location, likely on doc.php.net, and > post the snapshots there +1 > * Move all remaining inline PHP 4 references to their > respective changelog sections, or in cases that this does > not make sense, delete > I'm undecided here. On the one hand, it would be nice to see the "full" history of a function or feature ("Yo dawg, that function has been around since, like, forever!"). On the other hand, who cares? So long as we can see things that might be relevant to the version(s) of PHP that I'm using. If we're going to go to the trouble of creating a snapshot/archive, can we just nuke PHP 4 entirely from the "current" manual? > * Create php.net/manual/php4.php that: > * Discusses the PHP 4 situation > * Links to the doc snapshots > * Mentions that we don’t have a nice PHP 4 manual (sorry) > * Links to PHP 4 -> PHP 5 migration guide, and also 5.0->5.1, > and 5.1->5.2 is we go with 5.2 as the min version > * Links to older archive.org versions, like the following > shows the old domxml extension: > * > > https://web.archive.org/web/20120612062449/http://www.php.net/manual/en/book.domxml.php > I think that’s better than including entire extensions here > as that's too much clutter/noise > +1 I'd rather see one dedicated PHP 4 page that we can point people to, than a PHP 4 subsection of the manual (that we'd have to maintain) > Optionally, someone that really cares enough about PHP 4 can also: > > * Create snapshot based on old documentation that was before we > removed many old PHP 4 comments/extensions/removals, whenever > that was, and post them in /archives/ as downloads only > If we do create a downloadable snapshot, as alluded to above, I think it'd be a good idea to at least add back in things that are easy to add; like the removed extensions. > * Create a "What functions/extensions were removed in PHP 5" > guide, and include alternatives e.g., domxml->dom > This isn't already in the PHP 4 to 5 migration guide? *sad face* > * Create a tips guide for common problems PHP 4 code users face > in the world today > This caught my interest... what problems *do* PHP 4 code users face: other than constantly being told that they should upgrade? > > It appears the remaining questions are (I included my opinions): > > * Should we remove PHP 4-only functions/extensions? > - I think so > +1 > * What should the minimum PHP version be? 5.2.0? > - Yes, 5.2.0 seems fine * What does the "minimum PHP version" mean? > * If 5.2.0, do we remove functions only in 5.1 and below? > - No > * Or does it simply mean how we write and structure documentation? > - Yes, but this requires more explanation * Remove "PHP 4" from versions.xml? > - I’m on the fence, but lean towards removing the PHP 4 references > here as long as the add date is inserted into the respective > changelog sections > I'm not sure that having a version string at the top of the page say "(PHP 5)" then having a changelog entry saying "PHP 4.0.1: Function xyz() was added." makes a whole heap of sense. Half of me is saying, "get rid of PHP 4 entirely". The other half is nostalgic for those good old PHP 4 days. Yet another half (yes, three halves) wants there to be somewhere, anywhere, *in the PHP Manual* which tells me when a function/feature was introduced, even if it was in PHP 4. > * The current structure/layout was created with PHP 3 in mind, > with minor updates along the way. This might explain why the > appendix has grown out of control, why advanced features can > be hidden (not kept in mind when writing related docs), and > so on. Rethink our structure? Also, too much PECL clutter? > - One day yes, not right now ;) > I'd like to hear your thoughts on this, maybe off-list. :) > > Unfortunately, this task was started but never completed. Many people > tackled it differently (some created PHP 4 changelog entries, some simply > deleted PHP 4 references along the way, and so on), we won't have a > perfect solution. A true "snapshot" option is not possible. > I think that much we can all agree on. A remaining question is, what sort of archive will be "good enough"? > > Any glaring holes in the above summary? There must be one or three. :) > > Regards, > Philip > >