Use EBNF instead of images to render sqlgrams #4389

kennytm · 2020-12-10T10:34:31Z

Change Request

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

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.

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

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_]'+

The text was updated successfully, but these errors were encountered:

dveeden · 2021-04-09T06:49:51Z

Besides updating the things that predate this it might also be nice to add information into the README.md and/or CONTRIBUTING.md about how to work with the EBNF rendering and how to test it before submitting a PR.

dveeden · 2023-03-23T08:43:52Z

Current state:

$ git grep -c 'sqlgram/.*png'
functions-and-operators/set-operators.md:1
sql-statements/sql-statement-select.md:14
sql-statements/sql-statement-set-default-role.md:4
sql-statements/sql-statement-set-names.md:7
sql-statements/sql-statement-set-password.md:1
sql-statements/sql-statement-set-role.md:3
sql-statements/sql-statement-set-variable.md:2
sql-statements/sql-statement-show-bindings.md:4
sql-statements/sql-statement-show-builtins.md:1
sql-statements/sql-statement-show-character-set.md:2
sql-statements/sql-statement-show-collation.md:1
sql-statements/sql-statement-show-columns-from.md:10
sql-statements/sql-statement-show-config.md:2
sql-statements/sql-statement-show-create-sequence.md:2
sql-statements/sql-statement-show-create-table.md:2
sql-statements/sql-statement-show-create-user.md:2
sql-statements/sql-statement-show-databases.md:2
sql-statements/sql-statement-show-engines.md:1
sql-statements/sql-statement-show-errors.md:1
sql-statements/sql-statement-show-grants.md:5
sql-statements/sql-statement-show-histograms.md:3
sql-statements/sql-statement-show-indexes.md:5
sql-statements/sql-statement-show-plugins.md:2
sql-statements/sql-statement-show-privileges.md:1
sql-statements/sql-statement-show-processlist.md:2
sql-statements/sql-statement-show-profiles.md:1
sql-statements/sql-statement-show-stats-healthy.md:3
sql-statements/sql-statement-show-stats-meta.md:3
sql-statements/sql-statement-show-status.md:3
sql-statements/sql-statement-show-table-next-rowid.md:2
sql-statements/sql-statement-show-table-regions.md:5
sql-statements/sql-statement-show-table-status.md:3
sql-statements/sql-statement-show-tables.md:4
sql-statements/sql-statement-show-variables.md:3
sql-statements/sql-statement-show-warnings.md:1
sql-statements/sql-statement-shutdown.md:1
sql-statements/sql-statement-split-region.md:7
sql-statements/sql-statement-trace.md:2
sql-statements/sql-statement-truncate.md:3
sql-statements/sql-statement-update.md:6
sql-statements/sql-statement-use.md:2
statistics.md:3

dveeden · 2024-04-05T13:14:34Z

Maybe @terry1purcell can help with the statistics.md related sqlgrams/EBNF

dveeden · 2024-04-26T07:58:55Z

Current state:

$ git grep -c 'sqlgram/.*png'
functions-and-operators/set-operators.md:1
sql-statements/sql-statement-select.md:13
statistics.md:3

dveeden · 2024-05-27T07:16:59Z

Everything done. Thanks to everyone involved in this!

TomShawn added the lifecycle/frozen Issues with this label will not be labeled as "stale". label Dec 10, 2020

CharLotteiu mentioned this issue Jan 18, 2021

sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements pingcap/docs-cn#5324

Merged

10 tasks

This comment has been minimized.

Sign in to view

kennytm mentioned this issue Jan 19, 2021

remarkSyntaxDiagram: fix rendering of (x y z)* pingcap/website-docs#145

Merged

CharLotteiu mentioned this issue Jan 22, 2021

sql-statements: use EBNF to render syntax diagrams - second batch pingcap/docs-cn#5376

Merged

10 tasks

CharLotteiu mentioned this issue Feb 19, 2021

sql-statements: use EBNF to render syntax diagrams - third batch pingcap/docs-cn#5540

Merged

10 tasks

This was referenced Apr 26, 2021

sql-statements: use EBNF to render syntax diagrams - third batch (#5540) pingcap/docs-cn#6168

Merged

sql-statements: use EBNF to render syntax diagrams - third batch (#5540) pingcap/docs-cn#6169

Merged

CharLotteiu mentioned this issue Apr 27, 2021

sql-statements: use EBNF to render syntax diagrams - second batch #5531

Merged

10 tasks

This was referenced Apr 28, 2021

sql-statements: use EBNF to render syntax diagrams - second batch (#5531) #5536

Merged

sql-statements: use EBNF to render syntax diagrams - second batch (#5531) #5537

Merged

CharLotteiu mentioned this issue Apr 29, 2021

sql-statements: use EBNF to render syntax diagrams - third batch #5554

Merged

10 tasks

This was referenced Apr 30, 2021

sql-statements: use EBNF to render syntax diagrams - third batch (#5554) #5556

Merged

sql-statements: use EBNF to render syntax diagrams - third batch (#5554) #5557

Merged

Liuxiaozhen12 self-assigned this Jul 15, 2021

dveeden mentioned this issue Mar 23, 2023

select: Add tablesample #12979

Merged

15 tasks

This was referenced Jan 9, 2024

Change USE to ebnf and cleanup sqlgram #16049

Merged

truncate statement ebnf #16050

Merged

qiancai unassigned Liuxiaozhen12 Jan 9, 2024

dveeden mentioned this issue Jan 11, 2024

missing alt text pingcap/website-docs#463

Closed

qiancai mentioned this issue Feb 5, 2024

truncate statement ebnf pingcap/docs-cn#16510

Merged

17 tasks

ti-chi-bot mentioned this issue Feb 6, 2024

truncate statement ebnf (#16510) pingcap/docs-cn#16518

Merged

17 tasks

Oreoxmt mentioned this issue Mar 28, 2024

sql: change USE to ebnf pingcap/docs-cn#16928

Merged

17 tasks

dveeden mentioned this issue Apr 2, 2024

Rehash of statistics page #16869

Merged

18 tasks

dveeden removed the lifecycle/frozen Issues with this label will not be labeled as "stale". label Apr 5, 2024

This was referenced Apr 18, 2024

sql: change USE to ebnf (#16928) pingcap/docs-cn#17147

Merged

sql: change USE to ebnf (#16928) pingcap/docs-cn#17148

Merged

dveeden closed this as completed May 27, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use EBNF instead of images to render sqlgrams #4389

Use EBNF instead of images to render sqlgrams #4389

kennytm commented Dec 10, 2020 •

edited by dveeden

This comment has been minimized.

dveeden commented Apr 9, 2021

dveeden commented Mar 23, 2023

dveeden commented Apr 5, 2024

dveeden commented Apr 26, 2024

dveeden commented May 27, 2024

Use EBNF instead of images to render sqlgrams #4389

Use EBNF instead of images to render sqlgrams #4389

Comments

kennytm commented Dec 10, 2020 • edited by dveeden

Change Request

This comment has been minimized.

dveeden commented Apr 9, 2021

dveeden commented Mar 23, 2023

dveeden commented Apr 5, 2024

dveeden commented Apr 26, 2024

dveeden commented May 27, 2024

kennytm commented Dec 10, 2020 •

edited by dveeden