On Wed, Apr 11, 2012 at 01:19, Philip Olson <phi...@roshambo.org> wrote: > > On Apr 9, 2012, at 10:06 PM, Hannes Magnusson wrote: > >> 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. > > > Hi fellow geeks, > > We could make a special case for this, or use a non-note tag like <tip> or > <caution> although the <caution> tag scares me a little. Just a little. But > maybe it should. I'd feel more comfortable having the migration guide ready > before implementing that, so will begin work on said guide in the meantime. > > Most people here (and on IRC, #php.doc) have been expressing desire to make > this more visible than the current approach. That's understandable and I'm > beginning to agree. But remember, this is a suggestion and not deprecation, > and I think that's an important point to keep in mind at this stage. > > So how about this. We throw it into the description, and use a <note> or > <tip> for now. All of this text (except the suggested alternatives) will > be entities, so translations won't be out of date when we switch to caution, > warning, and beyond.
How about something along this way: http://imagebin.org/209085 Use <refsynopsisdiv> (with role="soft-deprecated-notice") and <sidebar> and move the info there, and then in phpweb specifically target it and position it and make it stand out. The other formats would get the blockquote in-your-face before the description refsect1. Attached is the suggested phpdoc change, phd and phpweb. The PhD change also includes the possibility of extending the support slightly in the future by automatically detecting deprecated functions during search/autocomplete to be able to suggest the alternatives. -Hannes
phd-deprecate.patch
Description: Binary data
phpdoc-deprecate.patch
Description: Binary data
phpweb-deprecate.patch
Description: Binary data
