search

pingcap / docs

TiDB database documentation.
https://docs.pingcap.com
Other
579 stars 671 forks source link

Use EBNF instead of images to render sqlgrams #4389

Closed kennytm closed 3 months ago

kennytm commented 3 years ago

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.

  1. Describe your suggestion or addition.

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

  1. 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 commented 3 years ago

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

2-fs8

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

1-fs8

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

1-fs8

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

1-fs8

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

1-fs8

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

dveeden commented 3 years ago

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 commented 1 year ago

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 commented 5 months ago

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

dveeden commented 4 months ago

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 commented 3 months ago

Everything done. Thanks to everyone involved in this!