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".
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.
Regards,
Philip
