split + rewrite query language chapter to new HQL guide document

documentation/documentation.gradle

@@ -194,6 +194,57 @@ tasks.register('renderIntroduction', AsciidoctorTask) {task->
 	}
 }
 
+tasks.register('renderQLPdf', AsciidoctorPdfTask) {task->
+	group = "Documentation"
+	description = 'Renders the Query Language document in PDF format using Asciidoctor.'
+	tasks.buildDocs.dependsOn task
+	tasks.buildDocsForPublishing.dependsOn task
+	inputs.property "hibernate-version", project.ormVersion
+
+	sourceDir = file( 'src/main/asciidoc/querylanguage' )
+	baseDir = file( 'src/main/asciidoc/querylanguage' )
+	sources {
+		include 'Hibernate_Query_Language.adoc'
+	}
+	outputDir = "$buildDir/asciidoc/querylanguage/pdf"
+
+	attributes jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/"
+}
+
+tasks.register('renderQL', AsciidoctorTask) {task->
+	group = "Documentation"
+	description = 'Renders the Query Language document in HTML format using Asciidoctor.'
+	tasks.buildDocs.dependsOn task
+	tasks.buildDocsForPublishing.dependsOn task
+	inputs.property "hibernate-version", project.ormVersion
+
+	sourceDir = file( 'src/main/asciidoc/querylanguage' )
+	sources {
+		include 'Hibernate_Query_Language.adoc'
+	}
+	outputDir = "$buildDir/asciidoc/querylanguage/html_single"
+
+	attributes linkcss: true,
+			stylesheet: "css/hibernate.css",
+			docinfo: 'private',
+			jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/"
+
+	resources {
+		from('src/main/asciidoc/querylanguage/') {
+			include 'images/**'
+		}
+		from('src/main/style/asciidoctor') {
+			include 'images/**'
+		}
+		from('src/main/style/asciidoctor') {
+			include 'css/**'
+		}
+		from('src/main/style/asciidoctor') {
+			include 'js/**'
+		}
+	}
+}
+
 // User Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 tasks.register('renderUserGuide', AsciidoctorTask) { task ->

documentation/src/main/asciidoc/introduction/Entities.adoc

@@ -1425,10 +1425,10 @@ Let's pause to remember the annotations we've met so far.
 |===
 | Annotation | Purpose | JPA-standard
 
-| `@Entity` | Declare an entity class | ✓
-| `@MappedSuperclass` | Declare a non-entity class with mapped attributes inherited by an entity | ✓
-| `@Embeddable` | Declare an embeddable type | ✓
-| `@IdClass` | declare the identifier class for an entity with multiple `@Id` attributes | ✓
+| `@Entity` | Declare an entity class | ✔
+| `@MappedSuperclass` | Declare a non-entity class with mapped attributes inherited by an entity | ✔
+| `@Embeddable` | Declare an embeddable type | ✔
+| `@IdClass` | declare the identifier class for an entity with multiple `@Id` attributes | ✔
 |===
 
 .Declaring basic attributes
@@ -1436,14 +1436,14 @@ Let's pause to remember the annotations we've met so far.
 |===
 | Annotation | Purpose | | JPA-standard
 
-| `@Id` | Declare a basic-typed identifier attribute | | ✓
-| `@Version` | Declare a version attribute | | ✓
-| `@Basic` | Declare a basic attribute | Default | ✓
-| `@EmbeddedId` | Declare an embeddable-typed identifier attribute | | ✓
-| `@Embedded` | Declare an embeddable-typed attribute | Inferred | ✓
-| `@Enumerated` | Declare an `enum`-typed attribute and specify how it is encoded | Inferred | ✓
-| `@Array` | Declare that an attribute maps to a SQL `ARRAY`, and specify the length | Inferred | ✗
-| `@ElementCollection` | Declare that a collection is mapped to a dedicated table | | ✓
+| `@Id` | Declare a basic-typed identifier attribute | | ✔
+| `@Version` | Declare a version attribute | | ✔
+| `@Basic` | Declare a basic attribute | Default | ✔
+| `@EmbeddedId` | Declare an embeddable-typed identifier attribute | | ✔
+| `@Embedded` | Declare an embeddable-typed attribute | Inferred | ✔
+| `@Enumerated` | Declare an `enum`-typed attribute and specify how it is encoded | Inferred | ✔
+| `@Array` | Declare that an attribute maps to a SQL `ARRAY`, and specify the length | Inferred | ✖
+| `@ElementCollection` | Declare that a collection is mapped to a dedicated table | | ✔
 |===
 
 .Converters and compositional basic types
@@ -1451,13 +1451,13 @@ Let's pause to remember the annotations we've met so far.
 |===
 | Annotation | Purpose | JPA-standard
 
-| `@Converter` | Register an `AttributeConverter` | ✓
-| `@Convert` | Apply a converter to an attribute | ✓
-| `@JavaType` | Explicitly specify an implementation of `JavaType` for a basic attribute | ✗
-| `@JdbcType` | Explicitly specify an implementation of `JdbcType` for a basic attribute | ✗
-| `@JdbcTypeCode` | Explicitly specify a JDBC type code used to determine the `JdbcType` for a basic attribute | ✗
-| `@JavaTypeRegistration` | Register a `JavaType` for a given Java type | ✗
-| `@JdbcTypeRegistration` | Register a `JdbcType` for a given JDBC type code | ✗
+| `@Converter` | Register an `AttributeConverter` | ✔
+| `@Convert` | Apply a converter to an attribute | ✔
+| `@JavaType` | Explicitly specify an implementation of `JavaType` for a basic attribute | ✖
+| `@JdbcType` | Explicitly specify an implementation of `JdbcType` for a basic attribute | ✖
+| `@JdbcTypeCode` | Explicitly specify a JDBC type code used to determine the `JdbcType` for a basic attribute | ✖
+| `@JavaTypeRegistration` | Register a `JavaType` for a given Java type | ✖
+| `@JdbcTypeRegistration` | Register a `JdbcType` for a given JDBC type code | ✖
 |===
 
 .System-generated identifiers
@@ -1465,11 +1465,11 @@ Let's pause to remember the annotations we've met so far.
 |===
 | Annotation | Purpose | JPA-standard
 
-| `@GeneratedValue` | Specify that an identifier is system-generated | ✓
-| `@SequenceGenerator` | Define an id generated backed by on a database sequence | ✓
-| `@TableGenerator` | Define an id generated backed by a database table | ✓
-| `@IdGeneratorType`  | Declare an annotation that associates a custom `Generator` with each `@Id` attribute it annotates | ✗
-| `@ValueGenerationType` | Declare an annotation that associates a custom `Generator` with each `@Basic` attribute it annotates | ✗
+| `@GeneratedValue` | Specify that an identifier is system-generated | ✔
+| `@SequenceGenerator` | Define an id generated backed by on a database sequence | ✔
+| `@TableGenerator` | Define an id generated backed by a database table | ✔
+| `@IdGeneratorType`  | Declare an annotation that associates a custom `Generator` with each `@Id` attribute it annotates | ✖
+| `@ValueGenerationType` | Declare an annotation that associates a custom `Generator` with each `@Basic` attribute it annotates | ✖
 |===
 
 .Declaring entity associations
@@ -1477,11 +1477,11 @@ Let's pause to remember the annotations we've met so far.
 |===
 | Annotation | Purpose | JPA-standard
 
-| `@ManyToOne` | Declare the single-valued side of a many-to-one association (the owning side) | ✓
-| `@OneToMany` | Declare the many-valued side of a many-to-one association (the unowned side) | ✓
-| `@ManyToMany` | Declare either side of a one-to-one association | ✓
-| `@OneToOne` | Declare either side of a one-to-one association | ✓
-| `@MapsId` | Declare that the owning side of a `@OneToOne` association maps the primary key column | ✓
+| `@ManyToOne` | Declare the single-valued side of a many-to-one association (the owning side) | ✔
+| `@OneToMany` | Declare the many-valued side of a many-to-one association (the unowned side) | ✔
+| `@ManyToMany` | Declare either side of a one-to-one association | ✔
+| `@OneToOne` | Declare either side of a one-to-one association | ✔
+| `@MapsId` | Declare that the owning side of a `@OneToOne` association maps the primary key column | ✔
 |===
 
 Phew!

documentation/src/main/asciidoc/introduction/Hibernate_Introduction.adoc

@@ -1,8 +1,8 @@
-:pdf-theme: theme.yml
+:pdf-theme: ../pdf/theme.yml
 :source-highlighter: rouge
 :icons: font
 :doctype: book
-:pdf-fontsdir: fonts
+:pdf-fontsdir: ../pdf/fonts
 :docsBase: https://docs.jboss.org/hibernate/orm
 :versionDocBase: {docsBase}/6.3
 :userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html
@@ -39,7 +39,7 @@ include::Mapping.adoc[]
 
 include::Interacting.adoc[]
 
-// include::../userguide/chapters/query/hql/QueryLanguage.adoc[]
+// include::../userguide/chapters/query/hql/Hibernate_Query_Language.adoc[]
 
 <<<
 

documentation/src/main/asciidoc/querylanguage/extras/group_by_item_bnf.txt

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

documentation/src/main/asciidoc/querylanguage/extras/hql-distinct-projection-query-example.sql

@@ -0,0 +1,4 @@
+select distinct
+    p.last_name
+from
+    person p

documentation/src/main/asciidoc/querylanguage/extras/hql-read-only-entities-example.sql

@@ -0,0 +1,12 @@
+select
+    c.id,
+    c.duration,
+    c.phone_id,
+    c.call_timestamp
+from
+    phone_call c
+join
+    Phone p
+        on p.id=c.phone_id
+where
+    p.phone_number='123-456-7890'

documentation/src/main/asciidoc/querylanguage/extras/limit_offset_bnf.txt

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

documentation/src/main/asciidoc/querylanguage/extras/order_by_item_bnf.txt

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

documentation/src/main/asciidoc/querylanguage/extras/predicate_in_bnf.txt

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

documentation/src/main/asciidoc/querylanguage/extras/predicate_like_bnf.txt

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

documentation/src/main/asciidoc/querylanguage/extras/searched_case_bnf.txt

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

documentation/src/main/asciidoc/querylanguage/extras/select_item_bnf.txt

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

documentation/src/main/asciidoc/querylanguage/extras/simple_case_bnf.txt

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

documentation/src/main/asciidoc/querylanguage/extras/statement_delete_bnf.txt

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

documentation/src/main/asciidoc/querylanguage/extras/statement_insert_bnf.txt

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

documentation/src/main/asciidoc/querylanguage/extras/statement_select_bnf.txt

@@ -0,0 +1,36 @@
+selectStatement
+	: queryExpression
+
+queryExpression
+	: withClause? orderedQuery (setOperator orderedQuery)*
+
+orderedQuery
+	: (query | "(" queryExpression ")") queryOrder?
+
+query
+	: selectClause fromClause? whereClause? (groupByClause havingClause?)?
+	| fromClause whereClause? (groupByClause havingClause?)? selectClause?
+
+queryOrder
+	: orderByClause limitClause? offsetClause? fetchClause?
+
+fromClause
+	: "FROM" entityWithJoins ("," entityWithJoins)*
+
+entityWithJoins
+	: fromRoot (join | crossJoin | jpaCollectionJoin)*
+
+fromRoot
+	: entityName variable?
+	| "LATERAL"? "(" subquery ")" variable?
+
+join
+	: joinType "JOIN" "FETCH"? joinTarget joinRestriction?
+
+joinTarget
+	: path variable?
+	| "LATERAL"? "(" subquery ")" variable?
+
+withClause
+	: "WITH" cte ("," cte)*
+	;

documentation/src/main/asciidoc/querylanguage/extras/statement_update_bnf.txt

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