On Apr 6, 2012, at 4:35 AM, Hannes Magnusson wrote: > On Fri, Apr 6, 2012 at 06:41, Philip Olson <phi...@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. Regards, Philip
