improve cross-links for ids and versions

spec/src/main/asciidoc/ch02-entities.adoc

@@ -456,24 +456,25 @@ A primary key must be defined exactly once in each entity hierarchy.
   of the entity class.
 - A _simple primary key_ is a single persistent field or property of the
   entity class whose type is one of the legal simple primary key types
-  listed below. The `Id` annotation or `id` XML element must be used to
-  identify the simple primary key. See <<a14827>>.
+  listed below. The `Id` annotation defined in <<a14827>> or `id` XML
+  element must be used to identify the simple primary key.
 - A _composite primary key_ must correspond to either a single persistent
   field or property, or to a set of fields or properties, as described
   below.footnote:[Composite primary keys often arise when mapping a legacy
   database with primary keys comprising multiple columns.] A _primary key
   class_ must be defined to represent the composite primary key.
-  * When the composite primary key corresponds to a single field or
-    property of the entity, the `EmbeddedId` annotation identifies the
-    primary key, and the type of the annotated field or property is the
-    primary key class. See <<a14687>>.
+  * If the composite primary key corresponds to a single field or property
+    of the entity, the `EmbeddedId` annotation defined by <<a14687>>
+    identifies the primary key, and the type of the annotated field or
+    property is the primary key class.
   * Otherwise, when the composite primary key corresponds to multiple
-    fields or properties, the `Id` annotation identifies the fields and
-    properties which comprise the composite key, and the `IdClass`
-    annotation is used to specify the primary key class. See <<a14836>>.
+    fields or properties, the `Id` annotation defined by <<a14827>>
+    identifies the fields and properties which comprise the composite key,
+    and the `IdClass` annotation defined by <<a14836>> must specify the
+    primary key class.
 
 A simple primary key or field or property belonging to a composite primary
-key should have one of the following types:
+key should have one of the following basic types:
 
 - any Java primitive type, or `java.lang` wrapper for a primitive type,
   footnote:[In general, however, approximate numeric types (e.g.,
@@ -484,17 +485,19 @@ key should have one of the following types:
 - `BigDecimal` or `BigInteger` from `java.math`.
 
 If a primary key field or property has type `java.util.Date`, the temporal
-type should be specified as `DATE`. See <<a16361>>.
+type must be explicitly specified as `DATE` using the `Temporal` annotation
+defined by <<a16361>>, or by equivalent XML.
 
 If the primary key is a composite primary key derived from the primary
 key of another entity, the primary key may contain an attribute whose
-type is that of the primary key of the referenced entity. See <<a149>>.
+type is that of the primary key of the referenced entity, as specified
+below in <<a149>>.
 
 An entity with a primary key involving any type other than the types
-listed above is not portable. If the primary key is generated, and its
-type is not `java.util.UUID`, `java.lang.String`, `java.lang.Long`,
-`java.lang.Integer`, `long`, or `int`, the entity is not portable.
-See <<a14790>>.
+listed above is not portable. If the primary key is generated by the
+persistence provider, as defined by <<a14790>>, and its type is not
+`long`, `int`, `java.util.UUID`, `java.lang.String`, `java.lang.Long`,
+or `java.lang.Integer`, the entity is not portable.
 
 The application must not change the value of the primary key of an entity
 instance after the instance is made persistentfootnote:[This includes not
@@ -517,7 +520,7 @@ The following rules apply to composite primary keys:
 - The access type (`FIELD` or `PROPERTY`) of a primary key class is
   determined by the access type of the entity for which it is the primary
   key, unless the primary key is an embedded id and an explicit access type
-  is specified using the `Access` annotation. See <<a113>>.
+  is specified using the `Access` annotation, as defined in <<a122>>.
 
 - If property-based access is used, the properties of the primary key class
   must be public or protected.
@@ -1216,20 +1219,28 @@ timestamp identifying the revision of the entity data held by an entity
 class instance. In the course of performing lifecycle operations involving
 the entity instance, the persistence provider gets and sets the version
 field or property of the entity instance to determine or modify its version
-number or timestamp.
+number or timestamp. The `Version` annotation defined in <<a16432>> or
+`version` XML element must be used to explicitly identify the version field
+or property of an entity.
 
 An entity class may access the state of its version field or property or
 export a method which allows other user-written code to access the version,
 but user-written code must not directly modify the value of the version
-field or property.footnote:[Bulk update statements, however, are permitted
-to set the version of an entity. See <<a5636>>.] With the exception noted
-in <<a5636>>, only the persistence provider is permitted to set or update
-the entity version.
+field or property of an entity instance after the entity is made persistent.
+footnote:[Bulk update statements, however, are permitted to set the version
+of an entity. See <<a5636>>.] With the exception noted in <<a5636>>, only
+the persistence provider is permitted to set or update the entity version.
+If the application does directly modify the value of the version field or
+property of an entity instance after it is made persistent, the behavior is
+undefined.
 
 The version must be of one of the following basic types:
-`int`, `Integer`, `short`, `Short`, `long`, `Long`, `LocalDateTime`,
-`Instant`, or `Timestamp`. A portable application must not declare
-a version field or property with any other type.
+
+- `int`, `Integer`, `short`, `Short`, `long`, `Long`, or
+- `java.time.LocalDateTime`, `java.time.Instant`, or `java.sql.Timestamp`.
+
+A portable application must not declare a version field or property with any
+other type.
 
 An entity class should have at most one version. A portable application
 must not define an entity class having more than one version field or