Bug #18877 | Documenting syntax changes | ||
---|---|---|---|
Submitted: | 7 Apr 2006 7:38 | Modified: | 16 Oct 2009 11:05 |
Reporter: | Keith Roberts | Email Updates: | |
Status: | Closed | Impact on me: | |
Category: | MySQL Server: Documentation | Severity: | S4 (Feature request) |
Version: | 5.0.18 | OS: | Linux (SuSE Linux 9.2 pro) |
Assigned to: | MC Brown | CPU Architecture: | Any |
[7 Apr 2006 7:38]
Keith Roberts
[10 Apr 2006 11:13]
Valeriy Kravchuk
Thank you for a problem report. Sounds like a reasonable (documentation) feature request (using exact BNFs, not their more "informal" representation) or even a build/QA procedure request.
[10 Apr 2006 15:31]
Keith Roberts
YW Valeriy - thankyou for your reply.
[15 Oct 2009 14:14]
MC Brown
We have added a new index that outlines the syntax for MySQL with references: http://dev.mysql.com/doc/refman/5.1/en/dynindex-statement.html A documentation project to handle the rest of this process and improve the output of the SQL Syntax, BNF and changes will be tackled in the future.
[15 Oct 2009 20:28]
Keith Roberts
The manual has improved greatly since my original report. I'm still concerned about user's having to wade through BNF to learn the mysql syntax. Would it not be better to produce proper syntax railroad diagrams for users? I find real syntax railroad diagrams a breeze to read. Just follow the arrows. SQLite uses a Tcl/Tk script to generate gif syntax diagrams. I think the script is under the same license as SQLite. Do you not think this would be worth doing for mysql?
[15 Oct 2009 20:31]
Keith Roberts
Richard Hipp's TCL bubble-generator.tcl wish script
Attachment: bubble-generator.tcl (text/x-tcl), 30.65 KiB.
[15 Oct 2009 20:38]
Keith Roberts
An example railroad syntax diagram for SQLite as created by Dr. R. Hipp's bubble-generator.tcl is at: http://www.sqlite.org/lang_createtable.html This is for the CREATE TABLE syntax. A lot easier to read than the equivalent BNF. Something like this would make understanding mysql CREATE TABLE (and all of the other mysql syntax) alot easier and quicker to comprehend IMHO :)
[16 Oct 2009 8:41]
MC Brown
Yes, railroad diagrams and improvements to the display and layout of the BNF are part of the project I mentioned.
[16 Oct 2009 11:05]
Keith Roberts
What I was going to suggest would be some type of meta-data for the mysql language syntax. That could then be used as the canonical reference for generating the mysql parser code, and also generating the mysql syntax railroad diagrams. So any changes the developers make to the mysql language could be made in one place - ie the language meta-data. This could them be used by a script to automatically generate the mysql syntax parser code, and the appropriate syntax railroad diagrams, all from that one meta-data source. This would then keep the railroad syntax diagrams in sync with the actual mysql program code that generates the mysql parser. ( Got this idea from Pragmatic Programmers by Andy Hunt & Dave Thomas. They call this the DRY principle - Don't Repeat Yourself! )