On Fri, Oct 22, 2010 at 3:49 PM, Daniel Bartholomew <dbart@askmonty.org> wrote:
Actually, the order that most KB pages follow is:
* Syntax * Description * Example(s)
The virtual columns page is kind of an aberration in that it has the description first, then syntax, then examples.
The reason for putting examples last is because some of the examples can get quite long (especially if they need explaining), so putting them at the bottom is better.
Yes. So to put what I said in another way, at the start of the description, I'd like to see a basic example showing the most common usage :-)
Henrik> Also, I propose we adopt the practice from the PostgreSQL Henrik> manual of always including last a section on which standards Henrik> the feature conforms to (or if it is MySQL specific, or MariaDB Henrik> specific feature, state that).
Sure, that would be a good thing to add. But like many good ideas, the devil is in the details.
Knowing whether an item is MySQL or MariaDB specific is pretty easy.
Stating whether a feature is standards compliant sounds quite a bit harder since I'm not an expert on the SQL standard. I know there are people out there who can simply look at, for example, the MariaDB ALTER TABLE syntax definition and state "yes, this conforms to SQL standard version XX" (or whatever), but I'm not one of those people. :) Do you know if there is anything existing that we can use that has this standards compliance information already?
Officially it isn't publicly available, but googling for it... http://www.contrib.andrew.cmu.edu/~shadow/sql/sql1992.txt However, to know what is fro SQL-92, SQL-99 etc... is difficult, I surely don't. ...in practice the easiest thing to do is to look at the PostgreSQL manual. That will get us pretty far already. (I see the beginning of a documentation howto :-) henrik -- henrik.ingo@avoinelama.fi +358-40-5697354 www.openlife.cc