Обсуждение: Railroad diagrams, a-la sqlite
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
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
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 > > > >
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 >
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
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 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
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 , 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
Вложения
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