← Back to team overview

maria-docs team mailing list archive

Re: Please use "syntax, example, text, standards conformity" as format for reference manual type of pages


On Fri, Oct 22, 2010 at 3:49 PM, Daniel Bartholomew <dbart@xxxxxxxxxxxx> 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...

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 :-)