pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedRailroad diagrams, a-la sqlite
15+ messages / 9 participants
[nested] [flat]
* Railroad diagrams, a-la sqlite
@ 2010-07-17 04:33 Steve Atkins <steve@blighty.com>
0 siblings, 3 replies; 15+ messages in thread
From: Steve Atkins @ 2010-07-17 04:33 UTC (permalink / raw)
To: pgsql-docs
Has everyone seen the "railroad diagrams" sqlite use in their docs? http://www.sqlite.org/lang_createindex.html , as one example.
Would it be nice to have the same sort of format in the postgresql docs? (Yeah, I'm volunteering, if people think they're a useful thing, 'cos I think they'd add a lot to our documentation.)
Cheers,
Steve
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: Railroad diagrams, a-la sqlite
@ 2010-07-17 05:30 Heikki Linnakangas <heikki.linnakangas@enterprisedb.com>
parent: Steve Atkins <steve@blighty.com>
2 siblings, 2 replies; 15+ messages in thread
From: Heikki Linnakangas @ 2010-07-17 05:30 UTC (permalink / raw)
To: Steve Atkins <steve@blighty.com>; +Cc: pgsql-docs
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 one example.
>
> Would it be nice to have the same sort of format in the postgresql docs? (Yeah, I'm volunteering, if people think they're a 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
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: Railroad diagrams, a-la sqlite
@ 2010-07-17 07:02 Hannu Krosing <hannu@krosing.net>
parent: Heikki Linnakangas <heikki.linnakangas@enterprisedb.com>
1 sibling, 1 reply; 15+ messages in thread
From: Hannu Krosing @ 2010-07-17 07:02 UTC (permalink / raw)
To: Heikki Linnakangas <heikki.linnakangas@enterprisedb.com>; +Cc: Steve Atkins <steve@blighty.com>; pgsql-docs
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 , as one example.
> >
> > Would it be nice to have the same sort of format in the postgresql docs? (Yeah, I'm volunteering, if people think they're a 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
>
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: Railroad diagrams, a-la sqlite
@ 2010-07-17 07:12 Hannu Krosing <hannu@krosing.net>
parent: Hannu Krosing <hannu@krosing.net>
0 siblings, 0 replies; 15+ messages in thread
From: Hannu Krosing @ 2010-07-17 07:12 UTC (permalink / raw)
To: Heikki Linnakangas <heikki.linnakangas@enterprisedb.com>; +Cc: Steve Atkins <steve@blighty.com>; pgsql-docs
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 , as one example.
> > >
> > > Would it be nice to have the same sort of format in the postgresql docs? (Yeah, I'm volunteering, if people think they're a 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
> >
>
>
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: Railroad diagrams, a-la sqlite
@ 2010-07-17 14:30 Tom Lane <tgl@sss.pgh.pa.us>
parent: Steve Atkins <steve@blighty.com>
2 siblings, 1 reply; 15+ messages in thread
From: Tom Lane @ 2010-07-17 14:30 UTC (permalink / raw)
To: Steve Atkins <steve@blighty.com>; +Cc: pgsql-docs
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 one example.
They look great for simple cases, but I can't imagine them being very
useful for SELECT, as an example.
regards, tom lane
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: Railroad diagrams, a-la sqlite
@ 2010-07-17 19:53 Peter Eisentraut <peter_e@gmx.net>
parent: Heikki Linnakangas <heikki.linnakangas@enterprisedb.com>
1 sibling, 0 replies; 15+ messages in thread
From: Peter Eisentraut @ 2010-07-17 19:53 UTC (permalink / raw)
To: Heikki Linnakangas <heikki.linnakangas@enterprisedb.com>; +Cc: Steve Atkins <steve@blighty.com>; pgsql-docs
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
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: Railroad diagrams, a-la sqlite
@ 2010-07-17 20:19 Thom Brown <thombrown@gmail.com>
parent: Steve Atkins <steve@blighty.com>
2 siblings, 1 reply; 15+ messages in thread
From: Thom Brown @ 2010-07-17 20:19 UTC (permalink / raw)
To: Steve Atkins <steve@blighty.com>; +Cc: pgsql-docs
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 one example.
>
> Would it be nice to have the same sort of format in the postgresql docs? (Yeah, I'm volunteering, if people think they're a 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
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: Railroad diagrams, a-la sqlite
@ 2010-07-17 20:23 Dave Page <dpage@pgadmin.org>
parent: Thom Brown <thombrown@gmail.com>
0 siblings, 1 reply; 15+ messages in thread
From: Dave Page @ 2010-07-17 20:23 UTC (permalink / raw)
To: Thom Brown <thombrown@gmail.com>; +Cc: Steve Atkins <steve@blighty.com>; pgsql-docs
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
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: Railroad diagrams, a-la sqlite
@ 2010-07-17 20:26 Thom Brown <thombrown@gmail.com>
parent: Dave Page <dpage@pgadmin.org>
0 siblings, 1 reply; 15+ messages in thread
From: Thom Brown @ 2010-07-17 20:26 UTC (permalink / raw)
To: Dave Page <dpage@pgadmin.org>; +Cc: Steve Atkins <steve@blighty.com>; pgsql-docs
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
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: Railroad diagrams, a-la sqlite
@ 2010-07-17 20:30 Joseph Conway <mail@joeconway.com>
parent: Thom Brown <thombrown@gmail.com>
0 siblings, 1 reply; 15+ messages in thread
From: Joseph Conway @ 2010-07-17 20:30 UTC (permalink / raw)
To: Thom Brown <thombrown@gmail.com>; +Cc: Dave Page <dpage@pgadmin.org>; Steve Atkins <steve@blighty.com>; pgsql-docs
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
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: Railroad diagrams, a-la sqlite
@ 2010-07-17 20:36 Thom Brown <thombrown@gmail.com>
parent: Joseph Conway <mail@joeconway.com>
0 siblings, 1 reply; 15+ messages in thread
From: Thom Brown @ 2010-07-17 20:36 UTC (permalink / raw)
To: Joseph Conway <mail@joeconway.com>; +Cc: Dave Page <dpage@pgadmin.org>; Steve Atkins <steve@blighty.com>; pgsql-docs
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
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: Railroad diagrams, a-la sqlite
@ 2010-07-17 20:42 Heikki Linnakangas <heikki.linnakangas@enterprisedb.com>
parent: Thom Brown <thombrown@gmail.com>
0 siblings, 1 reply; 15+ messages in thread
From: Heikki Linnakangas @ 2010-07-17 20:42 UTC (permalink / raw)
To: Thom Brown <thombrown@gmail.com>; +Cc: Joseph Conway <mail@joeconway.com>; Dave Page <dpage@pgadmin.org>; Steve Atkins <steve@blighty.com>; pgsql-docs
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
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: Railroad diagrams, a-la sqlite
@ 2010-07-17 21:04 Tom Lane <tgl@sss.pgh.pa.us>
parent: Heikki Linnakangas <heikki.linnakangas@enterprisedb.com>
0 siblings, 0 replies; 15+ messages in thread
From: Tom Lane @ 2010-07-17 21:04 UTC (permalink / raw)
To: Heikki Linnakangas <heikki.linnakangas@enterprisedb.com>; +Cc: Thom Brown <thombrown@gmail.com>; Joseph Conway <mail@joeconway.com>; Dave Page <dpage@pgadmin.org>; Steve Atkins <steve@blighty.com>; pgsql-docs
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
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: Railroad diagrams, a-la sqlite
@ 2010-07-19 14:59 Joshua Tolley <eggyknap@gmail.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 15+ messages in thread
From: Joshua Tolley @ 2010-07-19 14:59 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Steve Atkins <steve@blighty.com>; pgsql-docs
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 , as one 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
Attachments:
signature.asc (application/pgp-signature, 196B) download
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: Railroad diagrams, a-la sqlite
@ 2010-07-19 15:08 Thom Brown <thombrown@gmail.com>
parent: Joshua Tolley <eggyknap@gmail.com>
0 siblings, 0 replies; 15+ messages in thread
From: Thom Brown @ 2010-07-19 15:08 UTC (permalink / raw)
To: Joshua Tolley <eggyknap@gmail.com>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; Steve Atkins <steve@blighty.com>; pgsql-docs
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 , as one 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
^ permalink raw reply [nested|flat] 15+ messages in thread
end of thread, other threads:[~2010-07-19 15:08 UTC | newest]
Thread overview: 15+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2010-07-17 04:33 Railroad diagrams, a-la sqlite Steve Atkins <steve@blighty.com>
2010-07-17 05:30 ` Heikki Linnakangas <heikki.linnakangas@enterprisedb.com>
2010-07-17 07:02 ` Hannu Krosing <hannu@krosing.net>
2010-07-17 07:12 ` Hannu Krosing <hannu@krosing.net>
2010-07-17 19:53 ` Peter Eisentraut <peter_e@gmx.net>
2010-07-17 14:30 ` Tom Lane <tgl@sss.pgh.pa.us>
2010-07-19 14:59 ` Joshua Tolley <eggyknap@gmail.com>
2010-07-19 15:08 ` Thom Brown <thombrown@gmail.com>
2010-07-17 20:19 ` Thom Brown <thombrown@gmail.com>
2010-07-17 20:23 ` Dave Page <dpage@pgadmin.org>
2010-07-17 20:26 ` Thom Brown <thombrown@gmail.com>
2010-07-17 20:30 ` Joseph Conway <mail@joeconway.com>
2010-07-17 20:36 ` Thom Brown <thombrown@gmail.com>
2010-07-17 20:42 ` Heikki Linnakangas <heikki.linnakangas@enterprisedb.com>
2010-07-17 21:04 ` Tom Lane <tgl@sss.pgh.pa.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox