Use EBNF instead of images to render sqlgrams

[kennytm]

Change Request

Please answer the following questions before submitting your issue. Thanks!

1. Describe what you find is inappropriate or missing in the existing docs.

Recently we support rendering EBNF code directly as SVG (sample: https://docs.pingcap.com/tidb/stable/sql-statement-backup), and thus no longer needs to use PNG images for the sqlgrams (see #4342 for details). We should upgrade the remaining docs to use the new feature.

2. Describe your suggestion or addition.

Change the following pages to use ```ebnf+diagram:

• basic-sql-operations.md
• expression-syntax.md (sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements docs-cn#5324)
• functions-and-operators/set-operators.md #17465
• mysql-compatibility.md
• sql-statements/sql-statement-add-column.md (sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements docs-cn#5324)
• sql-statements/sql-statement-add-index.md (sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements docs-cn#5324)
• sql-statements/sql-statement-admin-cancel-ddl.md (sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements docs-cn#5324)
• sql-statements/sql-statement-admin-check-table-index.md (sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements docs-cn#5324)
• sql-statements/sql-statement-admin-checksum-table.md (sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements docs-cn#5324)
• sql-statements/sql-statement-admin-show-ddl.md (sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements docs-cn#5324)
• sql-statements/sql-statement-admin.md (sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements docs-cn#5324)
• sql-statements/sql-statement-alter-database.md (sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements docs-cn#5324)
• sql-statements/sql-statement-alter-index.md (sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements docs-cn#5324)
• sql-statements/sql-statement-alter-instance.md (sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements docs-cn#5324)
• sql-statements/sql-statement-alter-table.md (sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements docs-cn#5324)
• sql-statements/sql-statement-alter-user.md (sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements docs-cn#5324)
• sql-statements/sql-statement-analyze-table.md (sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements docs-cn#5324)
• sql-statements/sql-statement-backup.md (sql-statements: use EBNF to render syntax diagrams for BACKUP and RESTORE #4342)
• sql-statements/sql-statement-begin.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-change-column.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-commit.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-create-binding.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-create-database.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-create-index.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-create-role.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-create-sequence.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-create-table-like.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-create-table.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-create-user.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-create-view.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-deallocate.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-delete.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-do.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-drop-binding.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-drop-column.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-drop-database.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-drop-index.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-drop-role.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-drop-sequence.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-drop-stats.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-drop-table.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-drop-user.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-drop-view.md (sql-statements: use EBNF to render syntax diagrams - second batch docs-cn#5376)
• sql-statements/sql-statement-execute.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-explain-analyze.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-explain.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-flashback-table.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-flush-privileges.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-flush-status.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-flush-tables.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-grant-privileges.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-grant-role.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-insert.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-kill.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-load-data.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-load-stats.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-modify-column.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-prepare.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-recover-table.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-rename-index.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-rename-table.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-replace.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-restore.md (sql-statements: use EBNF to render syntax diagrams for BACKUP and RESTORE #4342)
• sql-statements/sql-statement-revoke-privileges.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-revoke-role.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-rollback.md (sql-statements: use EBNF to render syntax diagrams - third batch docs-cn#5540)
• sql-statements/sql-statement-select.md #17274
• sql-statements/sql-statement-set-default-role.md #17042
• sql-statements/sql-statement-set-names.md #17090
• sql-statements/sql-statement-set-password.md #17001
• sql-statements/sql-statement-set-role.md #17044
• sql-statements/sql-statement-set-transaction.md
• sql-statements/sql-statement-set-variable.md #17046
• sql-statements/sql-statement-show-analyze-status.md
• sql-statements/sql-statement-show-backups.md (sql-statements: use EBNF to render syntax diagrams for BACKUP and RESTORE #4342)
• sql-statements/sql-statement-show-bindings.md #17032
• sql-statements/sql-statement-show-builtins.md #17008
• sql-statements/sql-statement-show-character-set.md #17034
• sql-statements/sql-statement-show-collation.md #17017
• sql-statements/sql-statement-show-columns-from.md #17086
• sql-statements/sql-statement-show-config.md #17024
• sql-statements/sql-statement-show-create-sequence.md #17048
• sql-statements/sql-statement-show-create-table.md #17088
• sql-statements/sql-statement-show-create-user.md #17073
• sql-statements/sql-statement-show-databases.md #17030
• sql-statements/sql-statement-show-engines.md #17005
• sql-statements/sql-statement-show-errors.md #17010
• sql-statements/sql-statement-show-grants.md #17080
• sql-statements/sql-statement-show-histograms.md #17050
• sql-statements/sql-statement-show-indexes.md #17084
• sql-statements/sql-statement-show-plugins.md #17003
• sql-statements/sql-statement-show-privileges.md #17026
• sql-statements/sql-statement-show-processlist.md #17022
• sql-statements/sql-statement-show-profiles.md #17069
• sql-statements/sql-statement-show-stats-healthy.md #17071
• sql-statements/sql-statement-show-stats-meta.md #17019
• sql-statements/sql-statement-show-status.md Update SHOW STATUS docs #15363
• sql-statements/sql-statement-show-table-next-rowid.md #17092
• sql-statements/sql-statement-show-table-regions.md #17094
• sql-statements/sql-statement-show-table-status.md #17064
• sql-statements/sql-statement-show-tables.md #17067
• sql-statements/sql-statement-show-variables.md #16999
• sql-statements/sql-statement-show-warnings.md #16997
• sql-statements/sql-statement-shutdown.md #16993
• sql-statements/sql-statement-split-region.md #17096
• sql-statements/sql-statement-start-transaction.md
• sql-statements/sql-statement-trace.md #16995
• sql-statements/sql-statement-truncate.md truncate statement ebnf #16050
• sql-statements/sql-statement-update.md #17098
• sql-statements/sql-statement-use.md Change USE to ebnf and cleanup sqlgram #16049
• statistics.md #17463
• Replace links to https://pingcap.github.io/sqlgram/ #17467

3. Provide some reference materials (documents, websites, etc) if you could.

You can use https://kennytm.github.io/website-docs/dist/ to preview the rendered result.

Supported grammar:

Grammar     ::= Production+
Production  ::= NonTerminal "::=" Choice
Choice      ::= Seq ('|' Seq)*
Seq         ::= Item+
Item        ::= Primary ('*' | '+' | '?')?
Primary     ::= Terminal | NonTerminal | '(' Choice ')'
Terminal    ::= '"' '[^"]'* '"' | "'" "[^']"* "'"
NonTerminal ::= '[0-9a-zA-Z_]'+

[kennytm]

🤔 I just realized when (x y z)* rendered the nodes will be traveled in opposite order.

But the old image, which flips the nodes, does not look good at all.

We could fix this by drawing it like ((x y z)+)? (CockroachDB's style):

Or like (ε | x y z)+ (Oracle's style):

Or like ε | (x y z)+ (SQLite3's style):

In any case the rendered result will need 3 rows instead of 2 rows.