Railroad diagrams, a-la sqlite
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
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
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.
Show quoted text
--
Heikki Linnakangas
EnterpriseDB http://www.enterprisedb.com
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 .
Show quoted text
--
Heikki Linnakangas
EnterpriseDB http://www.enterprisedb.com
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
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
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
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
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
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
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
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
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
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
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