PHP-Documentation is not a book for a final version, it should cover also new ext's. And how people which aren't involved in dev or doc should know, that there is a new extension available?
MySQL is a very special thing in that it is used very heavily. After we add mysqli to the build, it will pop up in search results, the TOC and other places. It will be right there by the side of the MySQL extension docs.
We need to have at least a clear explanaion on why there are two extensions, who should use what, what PHP versions they are in, so we can reduce confusion of our users. John already agreed to do this.
BTW we also have a TODO item here for Hartmut. We need to have a PHP 5 version availabilty information field in the docs now, not only PHP 3 and 4. Given that MySQLi is only available for PHP 5 if I understand correctly.
Also, we should add
to the ext/mysql docs that they won't work with 4.1+.
It works fine, but it depends on your configuration. If you decide to use the bundled lib with 4.1 server, you will run into several authentication problems of course.
The differences should be documented. It is not a problem for ncurses to have a few function protos and not more. But it is a problem for mysqli to not have an explanation as mysql is used by the very entry level people too, and they will get easily confused. We need some introductory explanation to point these users to.
And less importantly, the reference.xml currently holds
all constant information with most entries listing the
constant name as also the value, that's weird. Also,
why does there even need to be a constant values column?
Right, I can't see a sense too - maybe Hartmut or Goba have a clue?
BC IMHO. PHP 3 used to not have names for these values (like error constants). This is why values are listed by constants most of the time. Also if you store them in an array, or serialize() something contanining these constants it is handy to see what constants is that number.
I don't see a BC problem - we have the same problem with two oracle extensions, which aren't compatible. The ext/mysql supports an optional last parameter, which is a link - this makes it nearly impossible to support future releases of libmysql which added additional parameters to functions. If people don't need MySQL's fast and powerful api-features which were implemented in version 4.1, they still can use ext/mysql without any BC problems. Changing ext/mysql to support MySQL 4.1 api would break BC.
These are the things that should be in the docs IMHO to not confuse people. Function docs can wait. Some intro is needed before that is ready for building IMHO.
Goba