maria-docs team mailing list archive

[Daniel Bartholomew <dbart@xxxxxxxxxxxx>]

On Thu, 21 Oct 2010 20:48:11 +0300
Henrik Ingo <henrik.ingo@xxxxxxxxxxxxx> wrote:

Henrik> Hi Daniel
Henrik> 
Henrik> I was reading
Henrik> http://kb.askmonty.org/v/virtual-columns
Henrik> 
Henrik> ...compare the ordering of the storyline to
Henrik> http://dev.mysql.com/doc/refman/5.1/en/create-table.html
Henrik> 
Henrik> The one from MySQL manual works great for me:
Henrik> syntax first (this is what I most commonly need)
Henrik> basic example(s) second (usually need this too for complex
Henrik> syntax) more indepth text, exceptions, etc... come third

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.

Assuming the above order is fine with you, I'll update the VC page to
follow it.

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?

Thanks.

-- 
Daniel Bartholomew
Monty Program - http://askmonty.org