Re: ext/mysql updates (~deprecated)

On Tue, Apr 10, 2012 at 02:17, cythrawll <chadm@codeangel.org> wrote: > > On 04/09/2012 04:25 PM, Philip Olson wrote: >> >> On Apr 6, 2012, at 4:35 AM, Hannes Magnusson wrote: >> >>> On Fri, Apr 6, 2012 at 06:41, Philip Olson<philip@roshambo.org>  wrote: >>>> >>>> Hello everyone, >>>> >>>> I gently began the process of softly deprecating ext/mysql. Basically, >>>> all I did was add<note>'s to several ext/mysql functions (to demonstrate >>>> the concept), and added a related<para>  in the ext/mysql introduction. >>>> Although the PHP community has been asking people to move away from >>>> ext/mysql for years now, the idea here is to take the next [small] step >>>> to make it both clearer and easier. >>>> >>>> The aim of each<note>  is to: >>>>  - Generally refer to the alternatives >>>>   (mysqli and pdo_mysql) >>>>  - Specify methods within said alternatives >>>>   (e.g., mysql_connect->  mysqli_connect|pdo::__construct) >>>> >>>> Possible problems: >>>>  - Hidden (<note>  is near the bottom, and mixed with other notes) >>>>  - Confusion (ext/mysql functions linking to ext/mysqli >>>>   functions) >>> >>> >>> Isn't "see also" more appropriate? >>> >>> When the alternative isn't an exact mapping, like with >>> mysql_data_seek() =>  PDO::FETCH_ORI_ABS (I had to lookup wtf that >>> constant did) a better and more concrete example should be included >>> somewhere imo. >> >> That was the original idea but it doesn't feel ideal for this task. The >> <note>  feels closer, and lends itself to allowing additional information >> with the ability to insert explanations. So IMHO this<note>  is better >> than See Also links. >> >> As for the less intuitive alternatives (e.g., FETCH_ORI_ABS) I agree that >> it should include information, although in this case FETCH_ORI_ABS >> should be better documented and then a simple link would do. The detailed >> examples are probably better suited for the migration guide. >> >> > Is there a way we can put the <note> in the role="description" section (or a > reason why we shouldn't)? I think it needs to be above the "fold". > No, we have a notes role for a reason. It would just increase the confusion having bunch of alternative suggestions there. If the idea is to keep it as notes then the current location is ok. -Hannes