minor fixes to docs

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

@@ -196,11 +196,11 @@ JPQL-style ordinal parameters are numbered from `1`.
 Just like with named parameters, a ordinal parameter may appear multiple times in a query.
 
 [[jpql-api-ordinal-parameter-example]]
-.Positional parameter binding
+.Ordinal parameter binding
 ====
 [source, JAVA, indent=0]
 ----
-include::{sourcedir}/HQLTest.java[tags=jpql-api-positional-parameter-example]
+include::{sourcedir}/HQLTest.java[tags=jpql-api-ordinal-parameter-example]
 ----
 ====
 
@@ -415,7 +415,7 @@ See the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hi
 //
 //[source, JAVA, indent=0]
 //----
-//include::{sourcedir}/HQLTest.java[tags=hql-api-positional-parameter-example]
+//include::{sourcedir}/HQLTest.java[tags=hql-api-ordinal-parameter-example]
 //----
 //====
 //

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

@@ -1761,15 +1761,16 @@ Just like in SQL, `all` suppresses the elimination of duplicate results.
 
 By default, the results of the query are returned in an arbitrary order.
 The `order by` clause specifies a list of selected items used to order the results.
-The types of expressions considered valid as part of the `order by` clause include:
+Each item may be:
 
-* attributes of an entity or embeddable class,
+* an attribute of an entity or embeddable class,
-* scalar expressions such as arithmetic operations, functions, etc, and
+* a scalar expression involving arithmetic operators, function application, etc,
-* identification variables declared in the select clause.
+* an alias declared in the select list, or
+* an integers indicating the ordinal position of an item in the select list.
 
 [NOTE]
 ====
-The JPQL specification requires that all expressions occurring the `order by` clause must also occur in the `select` clause.
+The JPQL specification requires that every expression in the `order by` clause must also occur in the `select` clause.
 HQL does not enforce this restriction, but applications desiring database portability should be aware that some databases _do_.
 ====
 
@@ -1804,7 +1805,7 @@ The `limit` and `offset` clauses are an alternative to the use of `setMaxResults
 
 [TIP]
 ====
-If the `limit` or `offset` is parameterized, its much easier to use `setMaxResults()` or `setFirstResult()`.
+If the `limit` or `offset` is parameterized, it's much easier to use `setMaxResults()` or `setFirstResult()`.
 ====
 
 The SQL syntax `fetch first ... rows only` and `fetch next ... rows only` is also allowed.

documentation/src/main/asciidoc/userguide/chapters/query/native/Native.adoc

@@ -364,7 +364,7 @@ There's no such equivalent in Jakarta Persistence because the `jakarta.persisten
 [[sql-query-parameters]]
 === Parameters
 
-Native SQL queries support positional as well as named parameters:
+Native SQL queries support ordinal as well as named parameters:
 
 [[sql-jpa-query-parameters-example]]
 .Jakarta Persistence native query with parameters

documentation/src/test/java/org/hibernate/userguide/hql/HQLTest.java

@@ -753,14 +753,14 @@ public class HQLTest extends BaseEntityManagerFunctionalTestCase {
 	@Test
 	public void test_jpql_api_positional_parameter_example() {
 		doInJPA( this::entityManagerFactory, entityManager -> {
-			//tag::jpql-api-positional-parameter-example[]
+			//tag::jpql-api-ordinal-parameter-example[]
 			TypedQuery<Person> query = entityManager.createQuery(
 				"select p " +
 				"from Person p " +
 				"where p.name like ?1",
 				Person.class )
 			.setParameter( 1, "J%" );
-			//end::jpql-api-positional-parameter-example[]
+			//end::jpql-api-ordinal-parameter-example[]
 		});
 	}
 
@@ -928,14 +928,14 @@ public class HQLTest extends BaseEntityManagerFunctionalTestCase {
 		doInJPA( this::entityManagerFactory, entityManager -> {
 			Date timestamp = new Date(  );
 			QueryProducer session = entityManager.unwrap( Session.class );
-			//tag::hql-api-positional-parameter-example[]
+			//tag::hql-api-ordinal-parameter-example[]
 			org.hibernate.query.Query<Person> query = session.createQuery(
 				"select p " +
 				"from Person p " +
 				"where p.name like ?",
 				Person.class )
 			.setParameter( 1, "J%" );
-			//end::hql-api-positional-parameter-example[]
+			//end::hql-api-ordinal-parameter-example[]
 		});
 	}