> Two notes on this. > > - Noone said that PHP should be replaced with &php; in the manual, > in fact some people opposed this *idea*. So this was not a good idea > at all here. Thos suggesting &php; have not yet provided reasons > on why this would be good (or I have missed those reasons).
Sorry, I thought it has been approved before was added to entity list.
Comment in language-snippets says:
"These are here as helpers for manual consistency and brievety".
I doubt &safemode; entity could be useful, but look at sources: we have PHP vs <literal>PHP</literal> 4/5 vs <literal>PHP 4/5</literal>. Such entity could really improve consistency, couldn't it? :]. It could if the original idea was to use <literal>PHP</literal>.
Anyway, I'm going to revert it to PHP 4/5 (without <literal />). Is that ok?
*I* think it would be nice to get <literal>PHP</literal> out of the manual, and only write PHP instead, since PHP is not supposed to be a literal in DocBook conventions.
This way &php; is useless indeed, I apologize and will revert migration5.xml.
It would be nice however if Damien or someone else who introduced that entity would provide us some insight on why he thinks using literal is better than not using it. Otherwise correcting would be another rush, which might lead to confusion at the end. It would be nice to know why this entity was introduced and if it would be a problem for anybody if we remove it and step back to using plain PHP instead of the literal enclosed PHP.
> I have planned on starting a discussion later on how that new PHP 5 OO > section should be built up, since it should be suitable for both PHP 4 > converts and those new to PHP. Therefore using 'objects are no longer' > or 'changed the behaviour' might not be correct in that section, since > it does not mean anything for newbies. It in fact makes their way > harder. Ideas?
> This is difficult.... I really have no ideas to OO. > Split the language reference OO in PHP 4 and 5?
Spliting could make harder way of PHP 4 developers are not familiar to OOP. But I suppose it would be best choise.
The language section *needs* to have a PHP 4 only OO part, since a lot of people will not upgrade for years, and they need this info. But since this is a language topic, the PHP 5 OO needs to be documented there (and not in migration, since this is new stuff, not migration related). So it is obvious that two different OO sections need to be in place in the language section, one for PHP 4 and one for PHP 5.
The real question is if the PHP 5 part should be written for absolute OO beginners, or written in the style of the zend-engine-2.php (as ported to DocBook by Boris), leading the reader from PHP 4 to PHP 5. That is: should we expect readers to know PHP 4 OO before reading PHP 5 OO, or we should not? For those coming from Java learning what PHP 5 OO can do, such stuff as 'unlike in PHP 4' or 'this was changed since PHP 4' will not mean anything...
I would suggest that we move the PHP 5 OO stuff into the language part from the migration part (new file in the language dir with language specific new IDs), and then read through it and identify the parts which would be problematic for those not knowing any OO, or coming from another language which is not PHP 4.
Boris, can you do this? It would be nice, if you could outline the process you would make (filenames, IDs, section titles), so we can discuss and approve it. That would eliminate any work we need to redo later.
Ok, I'll try to do that as soon as possible.
Goba
