Re: [DOCS] Railroad diagrams, a-la sqlite
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 > > > > -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Railroad diagrams, a-la sqlite
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 > -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Documentation and explanatory diagrams
Steve Atkins writes: > On Jul 16, 2010, at 7:20 PM, Robert Haas wrote: >> Unless I'm misunderstanding what you're talking about here, this is a >> really, really bad idea. > You're misunderstanding. Yeah, I think that in the main you guys are in violent agreement. > My feeling is that SVG is a decent lowest common denominator. I think this might be true in principle but not necessarily in practice. For example, if two tools write out SVG with different whitespace layout, that's going to kill diff-ing and VCS friendliness. This could probably be worked around, eg by settling on some particular tool as the one to run it through before committing (sort of a pgindent for graphics). But we need to do some experimentation with specific tools and see what the output really looks like and how it changes given small changes in the diagram, before we choose anything. regards, tom lane -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Railroad diagrams, a-la sqlite
Steve Atkins 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 -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Railroad diagrams, a-la sqlite
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 -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Railroad diagrams, a-la sqlite
On 17 July 2010 05: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.) > > 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 -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Railroad diagrams, a-la sqlite
On Sat, Jul 17, 2010 at 9:19 PM, Thom Brown 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 -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Railroad diagrams, a-la sqlite
On 17 July 2010 21:23, Dave Page wrote: > On Sat, Jul 17, 2010 at 9:19 PM, Thom Brown 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 -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Railroad diagrams, a-la sqlite
On 7/17/10 1:26 PM, Thom Brown wrote: > On 17 July 2010 21:23, Dave Page wrote: >> On Sat, Jul 17, 2010 at 9:19 PM, Thom Brown 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 -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Railroad diagrams, a-la sqlite
On 17 July 2010 21:30, Joseph Conway wrote: > On 7/17/10 1:26 PM, Thom Brown wrote: >> On 17 July 2010 21:23, Dave Page wrote: >>> On Sat, Jul 17, 2010 at 9:19 PM, Thom Brown 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 -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Railroad diagrams, a-la sqlite
On 17/07/10 23:36, Thom Brown wrote: On 17 July 2010 21:30, Joseph Conway wrote: On 7/17/10 1:26 PM, Thom Brown wrote: On 17 July 2010 21:23, Dave Page wrote: On Sat, Jul 17, 2010 at 9:19 PM, Thom Brown 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 -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Management of External Data (SQL/MED) in core?
On fre, 2010-07-16 at 13:25 +0100, Thom Brown wrote: > It's probably me not understanding what is being claimed, but on > http://www.postgresql.org/docs/8.4/static/features.html it says > PostgreSQL core covers ISO/IEC 9075-9 Management of External Data > (SQL/MED). I'm aware the actual SQL/MED functionality isn't > implemented yet. Is this purely to do with the provision of foreign > data wrappers, creating servers etc? Maybe "cover" isn't the right verb. It's about what is in scope and what is not. -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Railroad diagrams, a-la sqlite
Heikki Linnakangas writes: > On 17/07/10 23:36, Thom Brown wrote: >> On 17 July 2010 21:30, Joseph Conway 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 -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Documentation and explanatory diagrams
Tom Lane wrote: > Steve Atkins writes: > > On Jul 16, 2010, at 7:20 PM, Robert Haas wrote: > >> Unless I'm misunderstanding what you're talking about here, this is a > >> really, really bad idea. > > > You're misunderstanding. > > Yeah, I think that in the main you guys are in violent agreement. > > > My feeling is that SVG is a decent lowest common denominator. > > I think this might be true in principle but not necessarily in > practice. For example, if two tools write out SVG with different > whitespace layout, that's going to kill diff-ing and VCS friendliness. > This could probably be worked around, eg by settling on some particular > tool as the one to run it through before committing (sort of a pgindent > for graphics). But we need to do some experimentation with specific > tools and see what the output really looks like and how it changes > given small changes in the diagram, before we choose anything. Well, if we want _any_ images for the 9.0 docs, we had better decide soon. -- Bruce Momjian http://momjian.us EnterpriseDB http://enterprisedb.com + None of us is going to be here forever. + -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
