Thread: Railroad diagrams, a-la sqlite

Railroad diagrams, a-la sqlite

From
Steve Atkins
Date:
Has everyone seen the "railroad diagrams" sqlite use in their docs? http://www.sqlite.org/lang_createindex.html , as
oneexample. 

Would it be nice to have the same sort of format in the postgresql docs? (Yeah, I'm volunteering, if people think
they'rea useful thing, 'cos I think they'd add a lot to our documentation.) 

Cheers,
  Steve


Re: Railroad diagrams, a-la sqlite

From
Heikki Linnakangas
Date:
On 17/07/10 07:33, Steve Atkins wrote:
> Has everyone seen the "railroad diagrams" sqlite use in their docs? http://www.sqlite.org/lang_createindex.html , as
oneexample. 
>
> Would it be nice to have the same sort of format in the postgresql docs? (Yeah, I'm volunteering, if people think
they'rea useful thing, 'cos I think they'd add a lot to our documentation.) 

That would be nice. It would have to be automatically generated from the
syntax descriptions we already have, otherwise it'd be unmaintainable.
Also, the text representation would have to still be there in an alt tag
- I note that the the sqlite docs don't have that.

Any idea how those sqlite images are generated?

--
   Heikki Linnakangas
   EnterpriseDB   http://www.enterprisedb.com

Re: Railroad diagrams, a-la sqlite

From
Hannu Krosing
Date:
On Sat, 2010-07-17 at 10:02 +0300, Hannu Krosing wrote:
> On Sat, 2010-07-17 at 08:30 +0300, Heikki Linnakangas wrote:
> > On 17/07/10 07:33, Steve Atkins wrote:
> > > Has everyone seen the "railroad diagrams" sqlite use in their docs? http://www.sqlite.org/lang_createindex.html ,
asone example. 
> > >
> > > Would it be nice to have the same sort of format in the postgresql docs? (Yeah, I'm volunteering, if people think
they'rea useful thing, 'cos I think they'd add a lot to our documentation.) 
> >
> > That would be nice. It would have to be automatically generated from the
> > syntax descriptions we already have, otherwise it'd be unmaintainable.
> > Also, the text representation would have to still be there in an alt tag
> > - I note that the the sqlite docs don't have that.
> >
> > Any idea how those sqlite images are generated?
>
> I have used this:
>
> http://www.informatik.uni-freiburg.de/~thiemann/haskell/ebnf2ps/
>
> to make railroad diagrams from postgresql lex/yacc sources a few years
> ago, when looking into adding WITH support to pg.
>
> As it takes extended BNF as input i had to convert pg's lex+yacc into
> eBNF, which IIRC I did using some python scripts + manual tweaking.

Now it's readme says it does support yacc as one of input formats, so it
may be a lot simpler .

>
> > --
> >    Heikki Linnakangas
> >    EnterpriseDB   http://www.enterprisedb.com
> >
>
>



Re: Railroad diagrams, a-la sqlite

From
Hannu Krosing
Date:
On Sat, 2010-07-17 at 08:30 +0300, Heikki Linnakangas wrote:
> On 17/07/10 07:33, Steve Atkins wrote:
> > Has everyone seen the "railroad diagrams" sqlite use in their docs? http://www.sqlite.org/lang_createindex.html ,
asone example. 
> >
> > Would it be nice to have the same sort of format in the postgresql docs? (Yeah, I'm volunteering, if people think
they'rea useful thing, 'cos I think they'd add a lot to our documentation.) 
>
> That would be nice. It would have to be automatically generated from the
> syntax descriptions we already have, otherwise it'd be unmaintainable.
> Also, the text representation would have to still be there in an alt tag
> - I note that the the sqlite docs don't have that.
>
> Any idea how those sqlite images are generated?

I have used this:

http://www.informatik.uni-freiburg.de/~thiemann/haskell/ebnf2ps/

to make railroad diagrams from postgresql lex/yacc sources a few years
ago, when looking into adding WITH support to pg.

As it takes extended BNF as input i had to convert pg's lex+yacc into
eBNF, which IIRC I did using some python scripts + manual tweaking.


> --
>    Heikki Linnakangas
>    EnterpriseDB   http://www.enterprisedb.com
>



Re: Railroad diagrams, a-la sqlite

From
Tom Lane
Date:
Steve Atkins <steve@blighty.com> writes:
> Has everyone seen the "railroad diagrams" sqlite use in their docs? http://www.sqlite.org/lang_createindex.html , as
oneexample. 

They look great for simple cases, but I can't imagine them being very
useful for SELECT, as an example.

            regards, tom lane

Re: Railroad diagrams, a-la sqlite

From
Peter Eisentraut
Date:
On lör, 2010-07-17 at 08:30 +0300, Heikki Linnakangas wrote:
> Any idea how those sqlite images are generated?

http://stackoverflow.com/questions/773371/what-is-a-good-tool-for-creating-railroad-diagrams


Re: Railroad diagrams, a-la sqlite

From
Thom Brown
Date:
On 17 July 2010 05:33, Steve Atkins <steve@blighty.com> wrote:
> Has everyone seen the "railroad diagrams" sqlite use in their docs? http://www.sqlite.org/lang_createindex.html , as
oneexample. 
>
> Would it be nice to have the same sort of format in the postgresql docs? (Yeah, I'm volunteering, if people think
they'rea useful thing, 'cos I think they'd add a lot to our documentation.) 
>
> Cheers,
>  Steve
>

While they're quite attractive, I actually see them being more
confusing than helpful personally, but I could be wrong.  I reckon
there might be clearer ways of representing statement options.  The
real problems with the railroad design come when there are lots of
references to other diagrams, and you end up with about 10 just for 1
statement.

Is there a way of testing their usefulness?

Thom

Re: Railroad diagrams, a-la sqlite

From
Dave Page
Date:
On Sat, Jul 17, 2010 at 9:19 PM, Thom Brown <thombrown@gmail.com> wrote:
> While they're quite attractive, I actually see them being more
> confusing than helpful personally, but I could be wrong.  I reckon
> there might be clearer ways of representing statement options.  The
> real problems with the railroad design come when there are lots of
> references to other diagrams, and you end up with about 10 just for 1
> statement.
>
> Is there a way of testing their usefulness?

Personal experience? I used to find them quite useful when I was
starting out with Informix.

--
Dave Page
EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise Postgres Company

Re: Railroad diagrams, a-la sqlite

From
Thom Brown
Date:
On 17 July 2010 21:23, Dave Page <dpage@pgadmin.org> wrote:
> On Sat, Jul 17, 2010 at 9:19 PM, Thom Brown <thombrown@gmail.com> wrote:
>> While they're quite attractive, I actually see them being more
>> confusing than helpful personally, but I could be wrong.  I reckon
>> there might be clearer ways of representing statement options.  The
>> real problems with the railroad design come when there are lots of
>> references to other diagrams, and you end up with about 10 just for 1
>> statement.
>>
>> Is there a way of testing their usefulness?
>
> Personal experience? I used to find them quite useful when I was
> starting out with Informix.
>

I guess I'm quite used to the existing statement definitions.  It's an
elegant idea, just wondering if it scales sanely.  Are the examples of
more complex statements?

Thom

Re: Railroad diagrams, a-la sqlite

From
Joseph Conway
Date:
On 7/17/10 1:26 PM, Thom Brown wrote:
> On 17 July 2010 21:23, Dave Page <dpage@pgadmin.org> wrote:
>> On Sat, Jul 17, 2010 at 9:19 PM, Thom Brown <thombrown@gmail.com> wrote:
>>> While they're quite attractive, I actually see them being more
>>> confusing than helpful personally, but I could be wrong.  I reckon
>>> there might be clearer ways of representing statement options.  The
>>> real problems with the railroad design come when there are lots of
>>> references to other diagrams, and you end up with about 10 just for 1
>>> statement.
>>>
>>> Is there a way of testing their usefulness?
>>
>> Personal experience? I used to find them quite useful when I was
>> starting out with Informix.
>>
>
> I guess I'm quite used to the existing statement definitions.  It's an
> elegant idea, just wondering if it scales sanely.  Are the examples of
> more complex statements?

Oracle SELECT:

http://download.oracle.com/docs/cd/B14117_01/server.101/b10759/statements_10002.htm

Joe

--
Joe Conway
credativ LLC: http://www.credativ.us
Linux, PostgreSQL, and general Open Source
Training, Service, Consulting, & 24x7 Support


Re: Railroad diagrams, a-la sqlite

From
Thom Brown
Date:
On 17 July 2010 21:30, Joseph Conway <mail@joeconway.com> wrote:
> On 7/17/10 1:26 PM, Thom Brown wrote:
>> On 17 July 2010 21:23, Dave Page <dpage@pgadmin.org> wrote:
>>> On Sat, Jul 17, 2010 at 9:19 PM, Thom Brown <thombrown@gmail.com> wrote:
>>>> While they're quite attractive, I actually see them being more
>>>> confusing than helpful personally, but I could be wrong.  I reckon
>>>> there might be clearer ways of representing statement options.  The
>>>> real problems with the railroad design come when there are lots of
>>>> references to other diagrams, and you end up with about 10 just for 1
>>>> statement.
>>>>
>>>> Is there a way of testing their usefulness?
>>>
>>> Personal experience? I used to find them quite useful when I was
>>> starting out with Informix.
>>>
>>
>> I guess I'm quite used to the existing statement definitions.  It's an
>> elegant idea, just wondering if it scales sanely.  Are the examples of
>> more complex statements?
>
> Oracle SELECT:
>
> http://download.oracle.com/docs/cd/B14117_01/server.101/b10759/statements_10002.htm
>
> Joe
>

Yeah, that kinda chaotic.  Looks like a sadistic puzzle from the
Krypton Factor. :S

Thom

Re: Railroad diagrams, a-la sqlite

From
Heikki Linnakangas
Date:
On 17/07/10 23:36, Thom Brown wrote:
> On 17 July 2010 21:30, Joseph Conway<mail@joeconway.com>  wrote:
>> On 7/17/10 1:26 PM, Thom Brown wrote:
>>> On 17 July 2010 21:23, Dave Page<dpage@pgadmin.org>  wrote:
>>>> On Sat, Jul 17, 2010 at 9:19 PM, Thom Brown<thombrown@gmail.com>  wrote:
>>>>> While they're quite attractive, I actually see them being more
>>>>> confusing than helpful personally, but I could be wrong.  I reckon
>>>>> there might be clearer ways of representing statement options.  The
>>>>> real problems with the railroad design come when there are lots of
>>>>> references to other diagrams, and you end up with about 10 just for 1
>>>>> statement.
>>>>>
>>>>> Is there a way of testing their usefulness?
>>>>
>>>> Personal experience? I used to find them quite useful when I was
>>>> starting out with Informix.
>>>>
>>>
>>> I guess I'm quite used to the existing statement definitions.  It's an
>>> elegant idea, just wondering if it scales sanely.  Are the examples of
>>> more complex statements?
>>
>> Oracle SELECT:
>>
>> http://download.oracle.com/docs/cd/B14117_01/server.101/b10759/statements_10002.htm
>>
>> Joe
>>
>
> Yeah, that kinda chaotic.  Looks like a sadistic puzzle from the
> Krypton Factor. :S

Mind you, that syntax is genuinely complex. It would look chaotic using
the text representation we currently use as well.

--
   Heikki Linnakangas
   EnterpriseDB   http://www.enterprisedb.com

Re: Railroad diagrams, a-la sqlite

From
Tom Lane
Date:
Heikki Linnakangas <heikki.linnakangas@enterprisedb.com> writes:
> On 17/07/10 23:36, Thom Brown wrote:
>> On 17 July 2010 21:30, Joseph Conway<mail@joeconway.com>  wrote:
>>> Oracle SELECT:
>>> http://download.oracle.com/docs/cd/B14117_01/server.101/b10759/statements_10002.htm

>> Yeah, that kinda chaotic.  Looks like a sadistic puzzle from the
>> Krypton Factor. :S

> Mind you, that syntax is genuinely complex. It would look chaotic using
> the text representation we currently use as well.

Well, our own SELECT syntax isn't exactly short:
http://developer.postgresql.org/pgdocs/postgres/sql-select.html

The problem I personally see with railroad diagrams is that there's
so much whitespace in 'em.  Our current SELECT syntax diagram fits on
a page, more or less, but it would span multiple pages in railroad form.
That doesn't make for a leap forward in comprehensibility IMO.

            regards, tom lane

Re: Railroad diagrams, a-la sqlite

From
Joshua Tolley
Date:
On Sat, Jul 17, 2010 at 10:30:13AM -0400, Tom Lane wrote:
> Steve Atkins <steve@blighty.com> writes:
> > Has everyone seen the "railroad diagrams" sqlite use in their docs? http://www.sqlite.org/lang_createindex.html ,
asone example. 
>
> They look great for simple cases, but I can't imagine them being very
> useful for SELECT, as an example.

You mean like these from Oracle? http://is.gd/dya2n

In general, looking at those diagrams irritates me, but I think that's mostly
because Oracle's documentation irritates me generally. The SELECT version
speicifically is probably not terribly useful, IMO.

--
Joshua Tolley / eggyknap
End Point Corporation
http://www.endpoint.com

Attachment

Re: Railroad diagrams, a-la sqlite

From
Thom Brown
Date:
On 19 July 2010 15:59, Joshua Tolley <eggyknap@gmail.com> wrote:
> On Sat, Jul 17, 2010 at 10:30:13AM -0400, Tom Lane wrote:
>> Steve Atkins <steve@blighty.com> writes:
>> > Has everyone seen the "railroad diagrams" sqlite use in their docs? http://www.sqlite.org/lang_createindex.html ,
asone example. 
>>
>> They look great for simple cases, but I can't imagine them being very
>> useful for SELECT, as an example.
>
> You mean like these from Oracle? http://is.gd/dya2n
>
> In general, looking at those diagrams irritates me, but I think that's mostly
> because Oracle's documentation irritates me generally. The SELECT version
> speicifically is probably not terribly useful, IMO.
>

That page is an abomination!  Do they hate their users?

Thom