further improvements to xrefs

spec/src/main/asciidoc/appB-persistence.adoc

@@ -1,6 +1,8 @@
 [appendix]
 == Persistence API Interfaces [[persistence-api]]
 
+The following APIs are defined in the package `jakarta.persistence`.
+
 === `EntityManager` [[_entitymanager_]]
 [source,java]
 ----
@@ -31,7 +33,7 @@ include::../../../../api/src/main/java/jakarta/persistence/LockModeType.java[lin
 include::../../../../api/src/main/java/jakarta/persistence/Cache.java[lines=18..-1]
 ----
 
-=== `Query` [[a3127]]
+=== `Query` [[_query_]]
 [source,java]
 ----
 include::../../../../api/src/main/java/jakarta/persistence/Query.java[lines=18..-1]
@@ -103,7 +105,7 @@ include::../../../../api/src/main/java/jakarta/persistence/SchemaManager.java[li
 include::../../../../api/src/main/java/jakarta/persistence/Persistence.java[lines=18..-1]
 ----
 
-=== `PersistenceConfiguration`
+=== `PersistenceConfiguration` [[_persistenceconfiguration_]]
 [source,java]
 ----
 include::../../../../api/src/main/java/jakarta/persistence/PersistenceConfiguration.java[lines=18..-1]

spec/src/main/asciidoc/appC-criteria.adoc

@@ -1,6 +1,8 @@
 [appendix]
 == Criteria API Interfaces [[criteria-api]]
 
+The following APIs are defined in the package `jakarta.persistence.criteria`.
+
 === `CriteriaBuilder` [[_criteriabuilder_]]
 [source,java]
 ----

spec/src/main/asciidoc/appD-metamodel.adoc

@@ -1,12 +1,14 @@
 [appendix]
 == Metamodel API Interfaces [[metamodel-api]]
 
-=== `Metamodel`
+The following APIs are defined in the package `jakarta.persistence.metamodel`.
+
+=== `Metamodel` [[_metamodel_]]
 [source,java]
 ----
 include::../../../../api/src/main/java/jakarta/persistence/metamodel/Metamodel.java[lines=18..-1]
 ----
-=== `StaticMetamodel`
+=== `StaticMetamodel` [[_staticmetamodel_]]
 [source,java]
 ----
 include::../../../../api/src/main/java/jakarta/persistence/metamodel/StaticMetamodel.java[lines=18..-1]

spec/src/main/asciidoc/appE-spi.adoc

@@ -1,6 +1,8 @@
 [appendix]
 == Persistence SPI Interfaces [[persistence-spi]]
 
+The following APIs are defined in the package `jakarta.persistence.spi`.
+
 === `ClassTransformer` [[_classtransformer_]]
 [source,java]
 ----

spec/src/main/asciidoc/ch03-entity-operations.adoc

@@ -2685,16 +2685,21 @@ The following hint is defined by this specification for use in query configurati
 
  jakarta.persistence.query.timeout // time in milliseconds
 
-This hint may be used with the `Query`,
-`TypedQuery`, or `StoredProcedureQuery` `setHint` method or the
-`NamedQuery`, `NamedNativeQuery`, and `NamedStoredProcedureQuery`
-annotations. It may also be passed as a property to the
-`Persistence.createEntityManagerFactory` method and used in the
-`properties` element of the `persistence.xml` file. See <<a3127>>,
-<<a12384>>, <<a13443>>, <<a13710>>. When used in
-the `createEntityManagerFactory` method, the `persistence.xml` file, and
-annotations, the `timeout` hint serves as a default value which can be
-selectively overridden by use in the `setHint` method.
+This hint may:
+
+- be passed to the `setHint()` method of the `Query`, `TypedQuery`,
+  and `StoredProcedureQuery` interfaces found in <<persistence-api>>,
+- used with the `NamedQuery`, `NamedNativeQuery`, and
+  `NamedStoredProcedureQuery` annotations specified in <<a13710>>,
+- passed as a property to the `createEntityManagerFactory()` method
+  of the `Persistence` class, as defined in <<a13443>>, or
+- used in the `properties` element of the `persistence.xml` file, as
+  defined in <<a12384>>.
+
+The timeout specified by calling the `createEntityManagerFactory()`
+method, via the `persistence.xml` file, or in annotations, serves as
+a default value which can be selectively overridden by calling the
+`setHint()` method.
 
 Portable applications should not rely on this
 hint. Depending on the persistence provider and database in use, the

spec/src/main/asciidoc/ch05-metamodel-api.adoc

@@ -8,10 +8,9 @@ This specification provides a set of interfaces for dynamically accessing
 a metamodel representing the managed classes of a persistence unit.
 Instances of metamodel types may be obtained either:
 
-- via programmatic lookup using an instance of the interface
-  `jakarta.persistence.metamodel.Metamodel` obtained from the
-  `EntityManagerFactory` or `EntityManager` by calling
-  `getMetamodel()`, or
+- via programmatic lookup using an instance of the interface `Metamodel`
+  (found in <<_metamodel_>>) obtained from the `EntityManagerFactory` or
+  `EntityManager` by calling `getMetamodel()`, or
 - in a typesafe way, using _static metamodel classes_.
 
 A static metamodel class is a class with static members providing direct
@@ -47,11 +46,11 @@ this specification.]
 * The name of the metamodel class is derived from the name of the
 managed class by appending "`_`" to the name of the managed class.
 
-* The metamodel class `X_` must be annotated with the
-`jakarta.persistence.StaticMetamodel` annotationfootnote:[If the class
-was generated, the `javax.annotation.processing.Generated` or `jakarta.annotation.Generated`
-annotation should be used to annotate the class. The use of any other annotations on static
-metamodel classes is undefined.].
+* The metamodel class `X_` must be annotated with the `StaticMetamodel`
+annotation found in <<_staticmetamodel_>>.footnote:[If the class was
+generated, it should also be annotated with either
+`javax.annotation.processing.Generated` or `jakarta.annotation.Generated`.
+The use of any other annotations on static metamodel classes is undefined.]
 
 * If the managed class `X` extends another class `S`, where `S` is the
 most derived managed class (i.e., entity or mapped superclass) extended

spec/src/main/asciidoc/ch06-criteria-api.adoc

@@ -77,8 +77,7 @@ of the criteria API is described in <<a11349>>.
 === Constructing Criteria Queries [[a10614]]
 
 A criteria query is constructed through the creation and modification of
-an instance of `jakarta.persistence.criteria.CriteriaQuery`. This interface
-is found in <<_criteriaquery_>>.
+an instance of the `CriteriaQuery` interface found in <<_criteriaquery_>>.
 
 The `CriteriaBuilder` interface found in <<_criteriabuilder_>> is used to
 construct `CriteriaQuery`, `CriteriaUpdate`, and `CriteriaDelete` objects.

spec/src/main/asciidoc/ch09-container-provider-contracts.adoc

@@ -724,12 +724,12 @@ be used for vendor-specific information. The namespace
 
 === jakarta.persistence.PersistenceConfiguration Class [[a13444]]
 
-The `PersistenceConfiguration` class is used to programmatically define and
-configure a persistence unit and create an `EntityManagerFactory` instance
-directly. Thus, `PersistenceConfiguration` is an alternative to XML-based
-configuration using `persistence.xml`, and so the configuration options
-available via this API reflect the similarly-named elements of
-`persistence.xml`. See <<a12237>>.
+The `PersistenceConfiguration` class found in <<_persistenceconfiguration_>>
+is used to programmatically define and configure a persistence unit and create
+an `EntityManagerFactory` instance directly. Thus, `PersistenceConfiguration`
+is an alternative to XML-based configuration using `persistence.xml`, and so
+the configuration options available via this API reflect the similarly-named
+elements of `persistence.xml`. See <<a12237>>.
 
 A programmatically-configured persistence unit is considered a Java SE
 persistence unit, even when this API is used within the Jakarta EE

spec/src/main/asciidoc/ch10-metadata-annotations.adoc

@@ -235,6 +235,8 @@ public @interface NamedSubgraph {
 
 === Annotations for Queries [[a13710]]
 
+The following annotations are used to declare named queries.
+
 ==== NamedQuery Annotation [[a13711]]
 
 The `NamedQuery` annotation declared a named query written in the Jakarta