search

FirebirdSQL / firebird-documentation

Firebird documentation
https://www.firebirdsql.org/en/firebird-rdbms/
34 stars 14 forks source link

Change how SELECT syntax is documented #181

Closed mrotteveel closed 1 year ago

mrotteveel commented 1 year ago

Currently, the language reference documentation of the SELECT syntax uses a simplified form of documenting the syntax, refining details in different subsections, and ignoring some of the details of the syntax (e.g. by saying something can be <select-statement>, while the exact meaning of that depends on the context). The current syntax doesn't document the entire syntax of SELECT, and makes it hard to include some recent changes, like https://github.com/FirebirdSQL/firebird/issues/6740.

On the other hand, trying to document the syntax in its entirety may result in a hard to read mess. We need to look how we can improve this.

mrotteveel commented 1 year ago

As a first step, I added a separate section with the full syntax. This syntax uses the production names from the SQL standard. As a follow up step, I will try - where relevant - to replace current syntax productions with those from the full syntax, and try and integrate some other missing syntax in the other subsections.

mrotteveel commented 1 year ago

Further refined syntax to address most of the deficiencies. The global syntax documented in the introduction is still "too simple", but combined with the full syntax documented at the end, it should suffice.