On Tue, Apr 10, 2012 at 02:17, cythrawll <ch...@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<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. >> >> > 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
