make the BNFs more readable

and add one for grouped item

documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc

@@ -1882,6 +1882,16 @@ The `group by` clause looks quite similar to the `select` clause—it has a
 - if there's just one item, then the query will have a single result for each unique value of that item, or
 - if there are multiple items, the query will have a result for each unique _combination_ or their values.
 
+The BNF for a grouped item is just:
+
+[[hql-group-by-item-bnf]]
+====
+[source, antlrv4, indent=0]
+----
+include::{extrasdir}/group_by_item_bnf.txt[]
+----
+====
+
 Consider the following queries:
 
 [[hql-group-by-example]]

documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/group_by_item_bnf.txt

@@ -0,0 +1 @@
+identifier | INTEGER_LITERAL | expression

documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/limit_offset_bnf.txt

@@ -1,11 +1,11 @@
 limitClause
-    : LIMIT parameterOrIntegerLiteral
+    : "LIMIT" parameterOrIntegerLiteral
 
 offsetClause
-    : OFFSET parameterOrIntegerLiteral (ROW | ROWS)?
+    : "OFFSET" parameterOrIntegerLiteral ("ROW" | "ROWS")?
 
 fetchClause
-    : FETCH (FIRST | NEXT)
-      (parameterOrIntegerLiteral | parameterOrNumberLiteral PERCENT)
-      (ROW | ROWS)
-      (ONLY | WITH TIES)
+    : "FETCH" ("FIRST" | "NEXT")
+      (parameterOrIntegerLiteral | parameterOrNumberLiteral "%")
+      ("ROW" | "ROWS")
+      ("ONLY" | "WITH" "TIES")

documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/order_by_item_bnf.txt

@@ -1,10 +1,10 @@
-sortExpression orderingSpecification? nullsPrecedence?
+sortExpression sortDirection? nullsPrecedence?
 
 sortExpression
     : identifier | INTEGER_LITERAL | expression
 
-orderingSpecification
-    : ASC | DESC
+sortDirection
+    : "ASC" | "DESC"
 
 nullsPrecedence
-    : NULLS (FIRST | LAST)
+    : "NULLS" ("FIRST" | "LAST")

documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/predicate_in_bnf.txt

@@ -1,7 +1,7 @@
-expression NOT? IN inList
+expression "NOT"? "IN" inList
 
 inList
-	: (ELEMENTS|INDICES) LEFT_PAREN dotIdentifierSequence RIGHT_PAREN
-	| LEFT_PAREN (expression (COMMA expression)*)? RIGHT_PAREN
-	| LEFT_PAREN subquery RIGHT_PAREN
+	: ("ELEMENTS"|"INDICES") "(" simplePath ")"
+	| "(" (expression ("," expression)*)? ")"
+	| "(" subquery ")"
 	| parameter

documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/predicate_like_bnf.txt

@@ -1 +1 @@
-expression NOT? (LIKE | ILIKE) expression (ESCAPE character)?
+expression "NOT"? ("LIKE" | "ILIKE") expression ("ESCAPE" character)?

documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/searched_case_bnf.txt

@@ -1 +1 @@
-CASE (WHEN predicate THEN expression)+ (ELSE expression)? END
+"CASE" ("WHEN" predicate "THEN" expression)+ ("ELSE" expression)? "END"

documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/select_item_bnf.txt

@@ -1,7 +1,7 @@
 (expression | instantiation) alias?
 
 instantiation
-    : NEW instantiationTarget LEFT_PAREN instantiationArgs RIGHT_PAREN
+    : "NEW" instantiationTarget "(" instantiationArguments ")"
 
 alias
-    : AS? IDENTIFIER
+    : "AS"? IDENTIFIER

documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/simple_case_bnf.txt

@@ -1 +1 @@
-CASE expression (WHEN expression THEN expression)+ (ELSE expression)? END
+"CASE" expression ("WHEN" expression "THEN" expression)+ ("ELSE" expression)? END

documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_delete_bnf.txt

@@ -1 +1,2 @@
-deleteStatement : DELETE FROM? targetEntity whereClause?
+deleteStatement
+    : "DELETE" "FROM"? targetEntity whereClause?

documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_insert_bnf.txt

@@ -1 +1,14 @@
-insertStatement : INSERT INTO? targetEntity targetFields (queryExpression | valuesList)
+insertStatement
+    : "INSERT" "INTO"? targetEntity targetFields (queryExpression | valuesList)
+
+targetEntity
+	: entityName variable?
+
+targetFields
+	: "(" simplePath ("," simplePath)* ")"
+
+valuesList
+	: "VALUES" values ("," values)*
+
+values
+	: "(" expression ("," expression)* ")"

documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_select_bnf.txt

@@ -5,7 +5,7 @@ queryExpression
 	: orderedQuery (setOperator orderedQuery)*
 
 orderedQuery
-	: (query | LEFT_PAREN queryExpression RIGHT_PAREN) queryOrder?
+	: (query | "(" queryExpression ")") queryOrder?
 
 query
 	: selectClause fromClause? whereClause? (groupByClause havingClause?)?

documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_update_bnf.txt

@@ -1 +1,11 @@
-updateStatement : UPDATE VERSIONED? targetEntity setClause whereClause?
+updateStatement
+    : "UPDATE" "VERSIONED"? targetEntity setClause whereClause?
+
+targetEntity
+	: entityName variable?
+
+setClause
+	: "SET" assignment ("," assignment)*
+
+assignment
+    : simplePath "=" expression