Re: Lack of "real" example makes it very dificult to understand!

[Stefan Hinz]

I agree with you that the PHP documentation is very instructive, and that this is due to lots of what you call "real examples". But: You will probably notice, like I did, that when you're working with the PHP documentation, 90% of what you're reading is description of functions. It's easy to document functions, and give good examples for each function.
While MySQL has (SQL) functions, too, they make up for only 5% or so of what you would want to read. The rest is much more complex stuff (just two examples: SELECT/joins and MySQL configuration). If we'd go ahead and give "real examples" (which would take lots of space), we'd end up with a manual that was at least twice as big (and it's already huge). And we want to keep the MySQL manual what it is -- a reference manual, not an introductory book.
Last not least, I agree it's fairly easy to get started with PHP using nothing but the PHP documentation, if you have some programming background. At some point, however, you will want to read a couple of PHP books, to get more profound knowledge. With MySQL, it's probably more the other way around: You should read a couple of introductory books/tutorials first, and then read the MySQL manual to get more profound knowledge.

Stefan Hinz, MySQL Documentation, Berlin, Germany