On Fri, Oct 22, 2010 at 3:49 PM, Daniel Bartholomew <[email protected]> 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 -- [email protected] +358-40-5697354 www.openlife.cc _______________________________________________ Mailing list: https://launchpad.net/~maria-docs Post to : [email protected] Unsubscribe : https://launchpad.net/~maria-docs More help : https://help.launchpad.net/ListHelp
