add links between chapters

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

@@ -656,10 +656,20 @@ But in the country I was born, `SUNDAY` is the _first_ day of the week!
 So we prefer `@Enumerated(STRING)` for most `enum` attributes.
 ====
 
-An interesting special case is PostgreSQL.
+An interesting special case arises on PostgreSQL and Oracle.
-Postgres supports _named_ `ENUM` types, which must be declared using a DDL `CREATE TYPE` statement.
+
-Sadly, these `ENUM` types aren't well-integrated with the language nor well-supported by the Postgres JDBC driver, so Hibernate doesn't use them by default.
+[[named-enums]]
-But if you would like to use a named enumerated type on Postgres, just annotate your `enum` attribute like this:
+.Named enumerated types
+****
+Some databases support _named_ `ENUM` types, which must be declared using in DDL using:
+
+- `CREATE TYPE ... AS ENUM` on PostgreSQL, or
+- `CREATE DOMAIN ... AS ENUM` on Oracle.
+
+These look like a perfect match for Java ``enum``s, which also have names!
+
+Sadly, these `ENUM` types aren't well-integrated with the SQL language, nor well-supported by the JDBC drivers, so Hibernate doesn't use them by default.
+But if you would like to use a named enumerated type on Postgres or Oracle, just annotate your `enum` attribute like this:
 
 [source,java]
 ----
@@ -668,6 +678,9 @@ But if you would like to use a named enumerated type on Postgres, just annotate
 Status status;
 ----
 
+Alternatively, you may enable the configuration property link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#PREFER_NATIVE_ENUM_TYPES[`hibernate.type.prefer_native_enum_types`].
+****
+
 The limited set of pre-defined basic attribute types can be stretched a bit further by supplying a _converter_.
 
 [[converters]]
@@ -740,6 +753,7 @@ Hibernate considers a "basic type" to be formed by the marriage of two objects:
 
 When mapping a basic attribute, we may explicitly specify a `JavaType`, a `JdbcType`, or both.
 
+[[java-type]]
 [discrete]
 ==== JavaType
 
@@ -771,6 +785,7 @@ BitSet bitSet;
 
 Alternatively, the `@JavaTypeRegistration` annotation may be used to register `BitSetJavaType` as the default `JavaType` for `BitSet`.
 
+[[jdbc-type]]
 [discrete]
 ==== JdbcType
 

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

@@ -734,6 +734,7 @@ Of course, the behavior here depends very much on the JDBC driver, and so we rea
 
 There's a couple of alternative ways to represent an embeddable type on the database side.
 
+[[embeddable-udt]]
 [discrete]
 ==== Embeddables as UDTs
 
@@ -818,32 +819,33 @@ Here we summarize the ones we've just seen in the second half of this chapter, a
 |===
 | Annotation | Interpretation
 
-| `@Enumerated`, `@EnumeratedValue` | Specify how an `enum` type should be persisted
+| `@Enumerated`, `@EnumeratedValue` | Specify how an <<enums,`enum` type should be persisted>>
-| `@Nationalized` | Use a nationalized character type: `NCHAR`, `NVARCHAR`, or `NCLOB`
+| `@Nationalized` | Use a <<nationalized-chars,nationalized character type>>: `NCHAR`, `NVARCHAR`, or `NCLOB`
-| `@Lob` 💀 | Use JDBC LOB APIs to read and write the annotated attribute
+| `@Lob` 💀 | Use <<lobs,JDBC LOB APIs>> to read and write the annotated attribute
-| `@Array` | Map a collection to a SQL `ARRAY` type of the specified length
+| `@Array` | Map a collection to a <<arrays,SQL `ARRAY` type>> of the specified length
-| `@Struct` | Map an embeddable to a SQL UDT with the given name
+| `@Struct` | Map an <<embeddable-udt,embeddable to a SQL UDT>> with the given name
-| `@TimeZoneStorage` | Specify how the time zone information should be persisted
+| `@TimeZoneStorage` | Specify how the link:{doc-javadoc-url}org/hibernate/annotations/TimeZoneStorageType.html[time zone information should be persisted]
-| `@JdbcType` or `@JdbcTypeCode` | Use an implementation of `JdbcType` to map an arbitrary SQL type
+| `@JdbcType` or `@JdbcTypeCode` | Use an implementation of <<jdbc-type,`JdbcType`>> to map an arbitrary SQL type
 | `@Collate` | Specify a collation for a column
 |===
 
-In addition, there are link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html[some configuration properties] which have a _global_ affect on how basic types map to SQL column types:
+In addition, there are link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html[some configuration properties] which have a _global_ effect on how basic types map to SQL column types:
 
 .Type mapping settings
 [%autowidth.stretch]
 |===
 | Configuration property name | Purpose
 
-| `hibernate.use_nationalized_character_data` | Enable use of nationalized character types by default
+| `hibernate.use_nationalized_character_data` | Enable use of <<nationalized-chars,nationalized character types>> by default
-| `hibernate.type.preferred_boolean_jdbc_type` | Specify the default SQL column type for mapping `boolean`
+| `hibernate.type.preferred_boolean_jdbc_type` | Specify the default SQL column type for storing a `boolean`
-| `hibernate.type.preferred_uuid_jdbc_type` | Specify the default SQL column type for mapping `UUID`
+| `hibernate.type.preferred_uuid_jdbc_type` | Specify the default SQL column type for storing a `UUID`
-| `hibernate.type.preferred_duration_jdbc_type` | Specify the default SQL column type for mapping `Duration`
+| `hibernate.type.preferred_duration_jdbc_type` | Specify the default SQL column type for storing a `Duration`
-| `hibernate.type.preferred_instant_jdbc_type` | Specify the default SQL column type for mapping `Instant`
+| `hibernate.type.preferred_instant_jdbc_type` | Specify the default SQL column type for storing an `Instant`
-| `hibernate.timezone.default_storage` | Specify the default strategy for storing time zone information
+| `hibernate.timezone.default_storage` | Specify the default strategy for link:{doc-javadoc-url}org/hibernate/annotations/TimeZoneStorageType.html[storing time zone information]
+| `hibernate.type.prefer_native_enum_types` | Use <<named-enums,named enum types>> on PostgreSQL and Oracle
 |===
 
-For example, if we wanted to store an `Instant` using `timestamp with time zone` (called `timestamp` on MySQL, and `datetimeoffset` on SQL Server) instead of `timestamp` (`datetime` on MySQL, `datetime2` on SQL Server), then we could annotated every field of type `Instant`:
+For example, if we wanted to store an `Instant` using `timestamp with time zone` (called `timestamp` on MySQL, and `datetimeoffset` on SQL Server) instead of `timestamp` (`datetime` on MySQL, `datetime2` on SQL Server), then we could annotate every field of type `Instant`:
 
 [source,java]
 ----
@@ -851,7 +853,7 @@ For example, if we wanted to store an `Instant` using `timestamp with time zone`
 Instant instant;
 ----
 
-Alternatively, we could affect every field of type `Instant` with the property `hibernate.type.preferred_instant_jdbc_type`:
+Alternatively, we could set the property `hibernate.type.preferred_instant_jdbc_type`:
 
 
 [source,java]

documentation/src/main/asciidoc/querylanguage/Expressions.adoc

@@ -941,6 +941,7 @@ Its BNF is given by:
 "PAD" "(" expression "WITH" expression ("LEADING" | "TRAILING") padCharacter? ")"
 ----
 
+[[collations]]
 [discrete]
 ===== Collations
 

hibernate-core/src/main/java/org/hibernate/cfg/MappingSettings.java

@@ -279,6 +279,9 @@ public interface MappingSettings {
 	 *
 	 * @settingDefault {@link Dialect#getPreferredSqlTypeCodeForArray()}.
 	 *
+	 * @see org.hibernate.type.SqlTypes#ARRAY
+	 * @see org.hibernate.type.SqlTypes#TABLE
+	 *
 	 * @since 6.6
 	 */
 	@Incubating