HHH-16962 - General documentation improvements

https://hibernate.atlassian.net/browse/HHH-16962

documentation/src/main/asciidoc/integrationguide/Hibernate_Integration_Guide.adoc

@@ -1,11 +1,12 @@
-= Hibernate ORM {majorMinorVersion} Integration Guide
+= Hibernate ORM Integration Guide
-Steve Ebersole, Vlad Mihalcea
 :toc:
 :toclevels: 3
 
-include::Preface.adoc[]
+include::preface.adoc[]
 
 :numbered:
 
 include::chapters/services/Services.adoc[]
 
+include::credits.adoc[]
+

documentation/src/main/asciidoc/integrationguide/Preface.adoc

@@ -1,13 +0,0 @@
-[[preface]]
-== Preface
-
-Hibernate is an https://en.wikipedia.org/wiki/Object-relational_mapping[Object/Relational Mapping] solution for Java environments.
-
-Hibernate not only takes care of the mapping from Java classes to database tables (and from Java data types to SQL data types), but also provides data query and retrieval facilities.
-It can significantly reduce development time otherwise spent with manual data handling in SQL and JDBC.
-Hibernate’s design goal is to relieve the developer from 95% of common data persistence-related programming tasks by eliminating the need for manual, hand-crafted data processing using SQL and JDBC.
-However, unlike many other persistence solutions, Hibernate does not hide the power of SQL from you and guarantees that your investment in relational technology and knowledge is as valid as always.
-
-=== Audience
-
-This guide is for software developers and architects who will be integrating Hibernate with Java EE application servers, Spring framework, caching solutions (e.g. Infinispan, Ehcache, Hazelcast).

documentation/src/main/asciidoc/integrationguide/credits.adoc

@@ -0,0 +1,10 @@
+[[credits]]
+== Credits
+
+The full list of contributors to Hibernate ORM can be found on the
+https://github.com/hibernate/hibernate-orm/graphs/contributors[GitHub repository].
+
+The following contributors were involved in this documentation:
+
+* Steve Ebersole
+* Vlad Mihalcea

documentation/src/main/asciidoc/integrationguide/preface.adoc

@@ -0,0 +1,8 @@
+[[preface]]
+== Preface
+
+Hibernate provides many integration points that allow integration new capabilities or supplying custom behavior for standard capabilities.  This guide covers these integration points and is intended for software developers and architects who will be
+
+- integrating Hibernate with Java EE application servers, Spring framework, caching solutions (e.g. Infinispan, Ehcache, Hazelcast).
+- supplying custom integrations
+- want to override standard capabilities

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

@@ -119,7 +119,7 @@ This is completely by design and is not in any way a bug.
 More than one filter may be enabled in a given session.
 
 :envers: https://hibernate.org/orm/envers/
-:envers-doc: {userGuideBase}#envers
+:envers-doc: {doc-user-guide-url}#envers
 
 We've mentioned that a filter can be used to implement versioning, and to provide _historical_ views of the data.
 Being such a general-purpose construct, filters provide a lot of flexibility here.
@@ -592,7 +592,7 @@ Point event =
                 .getSingleResult();
 ----
 
-:matrix: {userGuideBase}#spatial-configuration-dialect-features
+:matrix: {doc-user-guide-url}#spatial-configuration-dialect-features
 
 Here, `within()` is one of the functions for testing spatial relations defined by the OpenGIS specification.
 Other such functions include `touches()`, `intersects()`, `distance()`, `boundary()`, etc.
@@ -806,7 +806,7 @@ Check constraints and foreign key constraints can help ensure that a row never c
 [[bytecode-enhancer]]
 === Using the bytecode enhancer
 
-:enhancer: {userGuideBase}#BytecodeEnhancement
+:enhancer: {doc-user-guide-url}#BytecodeEnhancement
 
 Hibernate's {enhancer}[bytecode enhancer] enables the following features:
 

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

@@ -77,7 +77,7 @@ Where `{version}` is the latest version of the JDBC driver for your databse.
 === Optional dependencies
 
 :slf4j: http://www.slf4j.org/
-:enhancer: {userGuideBase}#tooling-gradle
+:enhancer: {doc-user-guide-url}#tooling-gradle
 :agroal: https://agroal.github.io
 :jackson: https://github.com/FasterXML/jackson
 :yasson: https://projects.eclipse.org/projects/ee4j.yasson
@@ -231,7 +231,7 @@ SessionFactory sessionFactory =
 The `Configuration` class has survived almost unchanged since the very earliest (pre-1.0) versions of Hibernate, and so it doesn't look particularly modern.
 On the other hand, it's very easy to use, and exposes some options that `persistence.xml` doesn't support.
 
-:native-bootstrap: {userGuideBase}#bootstrap-native
+:native-bootstrap: {doc-user-guide-url}#bootstrap-native
 :boot: {versionDocBase}/javadocs/org/hibernate/boot/package-summary.html
 
 .Advanced configuration options

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

@@ -75,7 +75,7 @@ We won't have much more to say about XML-based mappings in this Introduction, si
 
 ."Dynamic" models
 ****
-:maps: {userGuideBase}#dynamic-model
+:maps: {doc-user-guide-url}#dynamic-model
 :envers: https://hibernate.org/orm/envers/
 We love representing entities as classes because the classes give us a _type-safe_ model of our data.
 But Hibernate also has the ability to represent entities as detyped instances of `java.util.Map`.

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

@@ -10,7 +10,7 @@ We've actually already seen its handiwork in the code examples <<main-jpa,earlie
 ****
 
 :generator: https://hibernate.org/orm/tooling/
-:generator-guide: {userGuideBase}#tooling-modelgen
+:generator-guide: {doc-user-guide-url}#tooling-modelgen
 
 Hibernate's {generator}[Metamodel Generator] is an annotation processor that produces what JPA calls a _static metamodel_.
 That is, it produces a typed model of the persistent classes in our program, giving us a type-safe way to refer to their attributes in Java code.

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

@@ -1,13 +1,12 @@
-:pdf-theme: ../pdf/theme.yml
+:shared-attributes-dir: ../shared/
-:source-highlighter: rouge
-:icons: font
-:doctype: book
-:pdf-fontsdir: ../pdf/fonts
-:docsBase: https://docs.jboss.org/hibernate/orm
-:versionDocBase: {docsBase}/6.3
-:userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html
 
-= A Guide to Hibernate 6
+include::{shared-attributes-dir}/common-attributes.adoc[]
+include::{shared-attributes-dir}/url-attributes.adoc[]
+include::{shared-attributes-dir}/filesystem-attributes.adoc[]
+include::{shared-attributes-dir}/renderer-attributes.adoc[]
+
+
+= An Introduction to Hibernate 6
 :title-logo-image: image:../../style/asciidoctor/images/org/hibernate/logo.png[]
 :toc:
 :toclevels: 3

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

@@ -512,7 +512,7 @@ It's not necessary to dirty-check on entity instance in read-only mode.
 [[queries]]
 === Queries
 
-:hql: {userGuideBase}#query-language
+:hql: {doc-user-guide-url}#query-language
 
 Hibernate features three complementary ways to write queries:
 
@@ -523,7 +523,7 @@ Hibernate features three complementary ways to write queries:
 [[hql-queries]]
 === HQL queries
 
-:hql: {userGuideBase}#query-language
+:hql: {doc-user-guide-url}#query-language
 
 A full discussion of the query language would require just as much text as the rest of this Introduction.
 Fortunately, HQL is already described in exhaustive (and exhausting) detail in _A guide to Hibernate Query Language 6_.

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

@@ -1,9 +1,6 @@
 [[preface]]
 == Preface
 
-:user-guide: {userGuideBase}
-:java-doc: {versionDocBase}/javadocs
-
 Hibernate 6 is a major redesign of the world's most popular and feature-rich ORM solution.
 The redesign has touched almost every subsystem of Hibernate, including the APIs, mapping annotations, and the query language.
 This new Hibernate is more powerful, more robust, and more typesafe.
@@ -23,9 +20,18 @@ Hibernate 6 and Hibernate Reactive are now core components of Quarkus 3, the mos
 
 Unfortunately, the changes in Hibernate 6 have obsoleted much of the information about Hibernate that's available in books, in blog posts, and on stackoverflow.
 
-On the other hand, the Hibernate {user-guide}[User Guide] provides a great deal of detail about many aspects of Hibernate, but with so much information to cover, readability is difficult to achieve.
 
-This is therefore the new canonical guide to Hibernate.
+This guide is an up-to-date, high-level discussion of the current set of Hibernate features.  It does not attempt
-We don't attempt to cover every detail of Hibernate here, and so this guide should be used in conjunction with the {java-doc}[extensive Javadoc] available for Hibernate 6.
+to cover every feature and should be used in conjunction with other documentation -
-Nor do we discuss the query language of Hibernate.
+
-And so this introduction should be used in conjunction with its sister document, _A guide to Hibernate Query Language 6_.
+- Hibernate's extensive link:{doc-javadoc-url}[Javadoc]
+- The link:{doc-query-language-url}[Hibernate Query Language Guide]
+- The Hibernate link:{doc-user-guide-url}[User Guide].
+
+[NOTE]
+====
+The Hibernate User Guide provides detailed discussion about most aspects of Hibernate.
+But with so much information to cover, readability is difficult to achieve - it should be considered more of a reference guide.
+
+Where applicable, this guide will provide links to detailed User Guide content within its covered topics.
+====

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

@@ -106,7 +106,7 @@ Even better than DML statement batching is the use of HQL `update` or `delete` q
 [[association-fetching]]
 === Association fetching
 
-:association-fetching: {userGuideBase}#fetching
+:association-fetching: {doc-user-guide-url}#fetching
 
 Achieving high performance in ORM means minimizing the number of round trips to the database. This goal should be uppermost in your mind whenever you're writing data access code with Hibernate. The most fundamental rule of thumb in ORM is:
 
@@ -352,7 +352,7 @@ In that case, we might be able to reduce the cost of cache misses by enabling ba
 [[second-level-cache]]
 === The second-level cache
 
-:second-level-cache: {userGuideBase}#caching
+:second-level-cache: {doc-user-guide-url}#caching
 
 A classic way to reduce the number of accesses to the database is to use a second-level cache, allowing  data cached in memory to be shared between sessions.
 

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

@@ -1,21 +1,15 @@
-:pdf-theme: ../pdf/theme.yml
+:shared-attributes-dir: ../shared/
-:source-highlighter: rouge
+
-:icons: font
+include::{shared-attributes-dir}/common-attributes.adoc[]
-:doctype: book
+include::{shared-attributes-dir}/url-attributes.adoc[]
-:pdf-fontsdir: ../pdf/fonts
+include::{shared-attributes-dir}/filesystem-attributes.adoc[]
-:docsBase: https://docs.jboss.org/hibernate/orm
+include::{shared-attributes-dir}/renderer-attributes.adoc[]
-:versionDocBase: {docsBase}/6.3
-:userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html
 
-:root-project-dir: ../../../../..
-:testing-project-dir: {root-project-dir}/hibernate-testing
 :example-dir-model: {testing-project-dir}/src/main/java/org/hibernate/testing/orm/domain/userguide
-:core-project-dir: {root-project-dir}/hibernate-core
 :example-dir-hql: {core-project-dir}/src/test/java/org/hibernate/orm/test/hql
 :extrasdir: extras
 
 = A Guide to Hibernate Query Language
-:title-logo-image: image:../../style/asciidoctor/images/org/hibernate/logo.png[]
 :toc:
 :toclevels: 3
 

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

@@ -1,4 +1,6 @@
-:introductionUrl: {versionDocBase}/querylanguage/html_single/Hibernate_Query_Language.html
+:shared-attributes-dir: ../shared/
+
+include::{shared-attributes-dir}/url-attributes.adoc[]
 
 [[preface]]
 == Preface
@@ -13,4 +15,4 @@ At long last, HQL has a feature set to match that of modern dialects of SQL, and
 
 This document is a reference guide to the full feature set of the language, and is the only up-to-date source for those who wish to learn how to write HQL effectively in Hibernate 6.
 
-If you don't already know Hibernate, first read link:{introductionUrl}[A Guide to Hibernate 6].
+If you are unfamiliar with Hibernate, be sure to first read  link:{doc-introduction-url}[Introduction to Hibernate] or check out the link:{doc-quick-start-url}[Quick Start].

documentation/src/main/asciidoc/quickstart/guides/credits.adoc

@@ -0,0 +1,9 @@
+[[credits]]
+== Credits
+
+The full list of contributors to Hibernate ORM can be found on the
+https://github.com/hibernate/hibernate-orm/graphs/contributors[GitHub repository].
+
+The following contributors were involved in this documentation:
+
+* Steve Ebersole

documentation/src/main/asciidoc/quickstart/guides/index.adoc

@@ -1,19 +1,24 @@
-:pdf-theme: ../../pdf/theme.yml
+:shared-attributes-dir: ../../shared/
-:source-highlighter: rouge
+
-:icons: font
+include::{shared-attributes-dir}/common-attributes.adoc[]
-:doctype: book
+include::{shared-attributes-dir}/url-attributes.adoc[]
-:pdf-fontsdir: ../../pdf/fonts
+include::{shared-attributes-dir}/filesystem-attributes.adoc[]
+include::{shared-attributes-dir}/renderer-attributes.adoc[]
 
 = Getting Started with Hibernate
-:title-logo-image: image:../../../style/asciidoctor/images/org/hibernate/logo.png[]
+:description: Quick start guide for Hibernate ORM
 :toc:
+:toclevels: 3
 :docinfo:
 
+include::preface.adoc[]
+
 :numbered:
+
 include::obtaining.adoc[]
 
 include::tutorial_annotations.adoc[]
-
 include::tutorial_jpa.adoc[]
-
 include::tutorial_envers.adoc[]
+
+include::credits.adoc[]

documentation/src/main/asciidoc/quickstart/guides/obtaining.adoc

@@ -1,84 +1,48 @@
-[[introduction]]
+[[obtaining]]
-== Introduction
+== Obtaining Hibernate
 
-Hibernate is an _Object/Relational Mapping_ (ORM) solution for programs written in Java and other JVM languages.
+Hibernate is broken into a number of modules/artifacts under the `org.hibernate.orm`
-It lets us map Java classes to database tables, and fields of the Java classes to columns of the tables, and then
+group.  The main artifact is named `hibernate-core`.
-takes over the most tedious work involved in executing SQL statements against the database. Hibernate typically
-eliminates upward of 90% of the work involved in common persistence-related programming tasks.
-
-However, unlike some other persistence solutions, Hibernate doesn't attempt to hide the relational model, nor take
-away the power of SQL as a query language. On the contrary, Hibernate centers the relational data, makes it visible
-to Java in a natural and typesafe object-oriented form, and offers an extremely powerful SQL-like query language for
-working with the data in Java.
 
 [NOTE]
-Hibernate may not be the best solution for data-centric applications where business logic is implemented in stored
-procedures. Hibernate is most useful for programs with an object-oriented domain model and business logic in a
-Java-based _middle tier_.
-
-[[resources]]
-.Resources
-****
-A strong background in SQL is not required to use Hibernate, at least not at first, but a basic understanding of the
-concepts is important.
-An understanding of _data modeling_ principles is especially important.
-Good starting points include:
-
-- https://www.agiledata.org/essays/dataModeling101.html[Data Modeling 101], and
-- https://en.wikipedia.org/wiki/Data_modeling[Wikipedia].
-
-If you're completely new to database access in Java, a decent overview of various technologies and options and how they
-fit together may be found at:
-
-- https://www.marcobehler.com/guides/a-guide-to-accessing-databases-in-java[Java & Databases: An Overview of Libraries & APIs].
-
-This guide will help you get up and running with Hibernate itself.
-But the best way to start learning Hibernate properly is the _Introduction to Hibernate 6_, available at
-https://hibernate.org/orm/documentation[the same place you got this document].
-
-[TIP]
 ====
-Of course, the other essential resource will be the documentation for your RDBMS, and especially the guide to the dialect
+This guide uses 6.3.0.Final as the Hibernate version for illustration purposes.  Be sure to change
-of SQL provided by your database.
+this version, if necessary, to the version you wish to use.
 ====
-****
 
-[[obtaining]]
+We can declare a dependency on this artifact using https://www.gradle.org[Gradle]
-=== Obtaining Hibernate
-
-We may obtain any Hibernate module we need just by declaring a dependency on the module in our Maven or Gradle build.
-We're certainly going to need `hibernate-core`, so we'll go ahead and declare a dependency on `org.hibernate.orm:hibernate-core`.
-
-In Gradle we would have:
 
 [source,groovy]
 ----
-implementation 'org.hibernate.orm:hibernate-core:6.3.0.Final'
+dependencies {
+  implementation "org.hibernate.orm:hibernate-core:6.3.0.Final"
+}
 ----
 
-Or in Maven:
+or https://maven.org[Maven]:
 
 [source,xml]
 ----
 <dependency>
-    <groupId>org.hibernate.org</groupId>
+    <groupId>org.hibernate.orm</groupId>
     <artifactId>hibernate-core</artifactId>
     <version>6.3.0.Final</version>
 </dependency>
 ----
 
 [[modules]]
-=== Modules belonging to Hibernate ORM
+=== Hibernate ORM modules
 
-Hibernate ORM is an umbrella project containing the following modules:
+As mentioned earlier, Hibernate ORM is broken into a number of modules with the intent of isolating
+transitive dependencies based on the features being used or not.
 
 [cols="40m,~"]
 .API-oriented modules
 |===
 |hibernate-core| The core object/relational mapping engine
 |hibernate-envers| Entity versioning and auditing
-|hibernate-spatial| Support for spatial/GIS data types
+|hibernate-spatial| Support for spatial/GIS data types using https://github.com/GeoLatte/geolatte-geom[GeoLatte]
-|hibernate-jpamodelgen| An annotation processor that generates a JPA-compliant metamodel
+|hibernate-jpamodelgen| An annotation processor that generates a JPA-compliant metamodel, plus optional Hibernate extras
 |===
 
 [cols="40m,~"]
@@ -90,20 +54,57 @@ Hibernate ORM is an umbrella project containing the following modules:
 |hibernate-vibur| Support for https://www.vibur.org/[Vibur DBCP] connection pooling
 |hibernate-proxool| Support for https://proxool.sourceforge.net/[Proxool] connection pooling
 |hibernate-jcache| Integration with https://jcp.org/en/jsr/detail?id=107$$[JCache], allowing any compliant implementation as a second-level cache provider
-|hibernate-community-dialects| Additional community-supported SQL dialects
 |hibernate-graalvm| Experimental extension to make it easier to compile applications as a https://www.graalvm.org/[GraalVM] native image
 |hibernate-micrometer| Integration with https://micrometer.io[Micrometer] metrics
+|hibernate-community-dialects| Additional community-supported SQL dialects
 |===
 
 [cols="40m,~"]
 .Testing-oriented modules
 |===
-|hibernate-testing| A framework for testing Hibernate ORM functionality
+|hibernate-testing| A series of JUnit extensions for testing Hibernate ORM functionality
-|hibernate-integrationtest-java-modules| Integration tests for running Hibernate ORM in the Java module path
 |===
 
-These artifacts are published under the Maven group id `org.hibernate.orm`.
+[[platform]]
+=== Platform / BOM
 
-[NOTE]
+Hibernate also provides a platform (BOM in Maven terminology) module which can be used to align versions of the Hibernate modules along with the versions of its libraries.  The platform artifact is named `hibernate-platform`.
-There's more to Hibernate than the modules belonging to the ORM project: Hibernate Search, Hibernate Reactive, Hibernate Validator, and more.
 
+To apply the platform in Gradle
+
+[source,groovy]
+----
+dependencies {
+  implementation platform "org.hibernate.orm:hibernate-platform:6.3.0.Final"
+
+  // use the versions from the platform
+  implementation "org.hibernate.orm:hibernate-core"
+  implementation "jakarta.transaction:jakarta.transaction-api"
+}
+----
+
+See the https://docs.gradle.org/current/userguide/java_platform_plugin.html#sec:java_platform_consumption[Gradle documentation] for capabilities of applying a platform.
+
+To apply the platform (BOM) in Maven
+
+[source,xml]
+----
+<dependency>
+    <groupId>org.hibernate.orm</groupId>
+    <artifactId>hibernate-core</artifactId>
+</dependency>
+<dependency>
+    <groupId>jakarta.transaction</groupId>
+    <artifactId>jakarta.transaction-api</artifactId>
+</dependency>
+
+<dependencyManagement>
+  <dependency>
+    <groupId>org.hibernate.orm</groupId>
+    <artifactId>hibernate-platform</artifactId>
+    <version>6.3.0.Final</version>
+    <type>pom</type>
+    <scope>import</scope>
+  </dependency>
+</dependencyManagement>
+----

documentation/src/main/asciidoc/quickstart/guides/preface.adoc

@@ -0,0 +1,12 @@
+:shared-attributes-dir: ../../shared/
+
+include::{shared-attributes-dir}/url-attributes.adoc[]
+include::{shared-attributes-dir}/filesystem-attributes.adoc[]
+
+[[preface]]
+== Preface
+
+Hibernate is an _Object/Relational Mapping_ (ORM) solution for programs written in Java and other JVM
+languages.
+
+include::{shared-attributes-dir}/background.adoc[]

documentation/src/main/asciidoc/quickstart/guides/tutorial_annotations.adoc

@@ -1,9 +1,12 @@
+:bootstrap-native-url: {doc-user-guide-url}#bootstrap-native
+:entity-model-url: {doc-user-guide-url}#entity
+
 [[tutorial_annotations]]
 == Tutorial using native Hibernate APIs
 
 .Objectives
 - [*] Configure Hibernate using `hibernate.properties`
-- [*] Create a `SessionFactory` using `org.hibernate.boot`
+- [*] Create a `SessionFactory` using link:{bootstrap-native-url}[native bootstrapping]
 - [*] Use annotations to provide mapping information
 - [*] Use `Session` to persist and query data
 
@@ -74,6 +77,9 @@ Observe that:
   Hibernate needs to instantiate objects for you, using Java Reflection.
   The constructor should have package-private or `public` visibility, to allow Hibernate to generate proxies and optimized code for field access.
 
+[NOTE]
+The link:{entity-model-url}[Entity types] section of the User Guide covers the complete set of requirements for the entity class.
+
 We use annotations to identify the class as an entity, and to map it to the relational schema.
 
 [[hibernate-gsg-tutorial-annotations-entity-entity]]
@@ -205,4 +211,5 @@ sessionFactory.inTransaction(session -> {
 - [ ] Actually run this example to see the SQL executed by Hibernate displayed in the console.
 - [ ] Reconfigure the examples to connect to your own persistent relational database.
 - [ ] Add an association to the `Event` entity to model a message thread.
-  See the _Introduction to Hibernate 6_ for details.
+
+// force the break

documentation/src/main/asciidoc/quickstart/guides/tutorial_envers.adoc

@@ -54,4 +54,6 @@ public void testBasicUsage() {
 - [*] Write a query to retrieve only historical data which meets some criteria. Use the _User Guide_ to see how
 Envers queries are constructed.
 - [*] Experiment with auditing entities which have various forms of relationships (many-to-one, many-to-many, etc).  Try
-retrieving historical versions (revisions) of such entities and navigating the object tree.
+retrieving historical versions (revisions) of such entities and navigating the object tree.
+
+// force the break

documentation/src/main/asciidoc/quickstart/guides/tutorial_jpa.adoc

@@ -55,15 +55,16 @@ In Java(TM) SE environments the persistence provider (Hibernate) is required to
 
 ----
 <1> A `persistence.xml` file should provide a unique name for each _persistence unit_ it declares.
-Applications use this name to reference the configuration when obtaining an `EntityManagerFactory`.
+Applications use this name to reference the configuration when obtaining an `EntityManagerFactory` as we will see shortly.
 <2> The `<class/>` element registers our annotated entity class.
 <3> The settings specified as `<properties/>` elements were already discussed in <<hibernate-gsg-tutorial-annotations-config>>.
 Here JPA-standard property names are used where possible.
 
 [NOTE]
+====
 Configuration properties prefixed with the legacy Java EE namespace `javax.persistence` are still
-recognized, but the Jakarta EE namespace `jakarta.persistence` is now preferred.
+recognized, but the Jakarta EE namespace `jakarta.persistence` should be preferred.
-
+====
 
 [[hibernate-gsg-tutorial-jpa-entity]]
 === The annotated entity Java class
@@ -77,14 +78,14 @@ The previous tutorials used Hibernate native APIs.
 This tutorial uses the standard Jakarta Persistence APIs.
 
 [[hibernate-gsg-tutorial-jpa-test-setUp]]
-.Obtaining the jakarta.persistence.EntityManagerFactory
+.Obtaining the JPA EntityManagerFactory
 [source, java]
 ----
 protected void setUp() {
-    sessionFactory = Persistence.createEntityManagerFactory("org.hibernate.tutorial.jpa");   <1>
+    entityManagerFactory = Persistence.createEntityManagerFactory("org.hibernate.tutorial.jpa");   <1>
 }
 ----
-<1> Notice again that the persistence unit name is `org.hibernate.tutorial.jpa`, which matches <<hibernate-gsg-tutorial-jpa-config-pu>>.
+<1> Notice again that the persistence unit name is `org.hibernate.tutorial.jpa`, which matches the name from our <<hibernate-gsg-tutorial-jpa-config-pu,persistence.xml>>.
 
 
 The code to persist and query entities is almost identical to <<hibernate-gsg-tutorial-basic-test-saving>>.
@@ -114,11 +115,13 @@ void inTransaction(Consumer<EntityManager> work) {
 ----
 
 [TIP]
-If you use JPA in Java SE, you'll need to copy/paste this function into your project.
+If you use JPA in Java SE, you'll need to copy/paste this function into your project.  Alternatively you could unwrap the `EntityManagerFactory` as a `SessionFactory`.
 
 [[hibernate-gsg-tutorial-jpa-further]]
 === Take it further!
 
 .Practice Exercises
 - [ ] Learn how to use CDI to inject a container-managed `EntityManager` in Quarkus.
-  See https://quarkus.io/guides/hibernate-orm[the Quarkus website] for instructions.
+  See https://quarkus.io/guides/hibernate-orm[the Quarkus website] for instructions.
+
+// force the break

documentation/src/main/asciidoc/shared/background.adoc

@@ -0,0 +1,12 @@
+
+While a strong background in SQL is not required to use Hibernate, a basic understanding of its concepts is useful - especially the principles of _data modeling_.
+Understanding the basics of transactions and design patterns such as _Unit of Work_ are important as well.
+
+[[useful-resources]]
+.Useful background resources
+****
+- https://en.wikipedia.org/wiki/Data_modeling[Data Modeling (Wikipedia)].
+- https://www.agiledata.org/essays/dataModeling101.html[Data Modeling 101]
+- https://www.marcobehler.com/guides/a-guide-to-accessing-databases-in-java[Java & Databases: An Overview of Libraries & APIs]
+- https://martinfowler.com/eaaCatalog/unitOfWork.html[Unit of Work]
+****

documentation/src/main/asciidoc/shared/common-attributes.adoc

@@ -0,0 +1,3 @@
+
+// NOTE : majorMinorVersion is injected by the build and will override this value
+:majorMinorVersion: 6.3

documentation/src/main/asciidoc/shared/filesystem-attributes.adoc

@@ -0,0 +1,15 @@
+// ****************************************************************************
+// Centralized definition of Asciidoc attributes for local filesystem paths
+// ****************************************************************************
+
+:doc-main-dir: ../..
+:doc-main-asciidoc-dir: {doc-main-dir}/asciidoc
+:doc-main-style-dir: {doc-main-dir}/style
+:pdf-theme: {doc-main-style-dir}/pdf/theme.yml
+:pdf-fontsdir: {doc-main-style-dir}/pdf/fonts
+//:title-logo-image: {doc-main-style-dir}/asciidoctor/images/org/hibernate/logo.png[]
+
+:root-project-dir: ../../../../..
+:core-project-dir: {root-project-dir}/hibernate-core
+:documentation-project-dir: {root-project-dir}/documentation
+:testing-project-dir: {root-project-dir}/hibernate-testing

documentation/src/main/asciidoc/shared/renderer-attributes.adoc

@@ -0,0 +1,3 @@
+:source-highlighter: rouge
+:icons: font
+:doctype: book

documentation/src/main/asciidoc/shared/url-attributes.adoc

@@ -0,0 +1,23 @@
+// ****************************************************************************
+// Centralized definition of Asciidoc attributes for documentation urls
+// ****************************************************************************
+
+include::./common-attributes.adoc[]
+
+:doc-base-url: https://docs.jboss.org/hibernate/orm
+:doc-version-base-url: {doc-base-url}/{majorMinorVersion}
+:doc-migration-guide-url: {doc-version-base-url}/migration-guide/migration-guide.html
+:doc-quick-start-url: {doc-version-base-url}/quickstart/html_single/
+:doc-query-language-url: {doc-version-base-url}/querylanguage/html_single/Hibernate_Query_Language.html
+:doc-introduction-url: {doc-version-base-url}/introduction/html_single/Hibernate_Introduction.html
+:doc-user-guide-url: {doc-version-base-url}/userguide/html_single/Hibernate_User_Guide.html
+:doc-javadoc-url: {doc-version-base-url}/javadocs/
+:doc-topical-url: {doc-version-base-url}/topical/html_single/
+:doc-registries-url: {doc-topical-url}/registries/ServiceRegistries.html
+:doc-logging-url: {doc-topical-url}/logging/Logging.html
+
+:report-deprecation-url: {doc-version-base-url}/deprecated/deprecating.txt
+:report-dialect-url: {doc-version-base-url}/dialect/dialect.html
+:report-incubating-url: {doc-version-base-url}/incubating/incubating.txt
+:report-internals-url: {doc-version-base-url}/internals/internal.txt
+:report-logging-url: {doc-version-base-url}/logging/logging.html

documentation/src/main/asciidoc/topical/index.adoc

@@ -1,36 +1,52 @@
+:shared-attributes-dir: ../shared/
+
+include::{shared-attributes-dir}/common-attributes.adoc[]
+include::{shared-attributes-dir}/url-attributes.adoc[]
+include::{shared-attributes-dir}/filesystem-attributes.adoc[]
+include::{shared-attributes-dir}/renderer-attributes.adoc[]
+
 = Topical Guides
-:userguide_rel_link: ../../userguide/html_single/Hibernate_User_Guide.html
-:integrationguid_rel_link: ../../integrationguide/html_single/Hibernate_Integration_Guide.html
-:migrationguide_rel_link: ../../migration-guide/migration-guide.html
-:logging_rel_link: ../../logging/logging.html
-:incubating_rel_link: ../../incubating/incubating.txt
-:internal_rel_link: ../../internals/internal.txt
 :toc:
 
 Hibernate documentation is organized into several guides that cover specific topics.  This guide provides links to
-all the guides to give some direction on where to look for information.
+all the documentation to give some direction on where to look for information.
 
-NOTE: This is still very much a work in progress. <<helping,Help>> is definitely welcome!
+[TIP]
-
+====
-== User Guides
+See the link:{doc-migration-guide-url}[Migration Guide] for details about migration to Hibernate {majorMinorVersion}.
-* For information on bootstrapping Hibernate
+====
-** For bootstrapping a SessionFactory, see the link:{userguide_rel_link}#bootstrap-native[Native Bootstrapping Guide]
-** For bootstrapping an EntityManagerFactory (Jakarta Persistence) using Hibernate, see the link:{userguide_rel_link}#bootstrap-jpa[Jakarta Persistence Bootstrap Guide]
-** For (semi-deprecated) bootstrapping of a SessionFactory using the legacy Configuration approach, see the link:{userguide_rel_link}#appendix-legacy-bootstrap[Legacy Bootstrap Guide]
-* For information on generated (non-identifier) values, see the <<generated/GeneratedValues.adoc#generated-values-guide,Generated Values Guide>>
-* Others coming soon
 
 
-== Migration
+[[usage-guides]]
-* For information on how to migrate to the current Hibernate 6 version check out the link:{migrationguide_rel_link}[Migration Guide]
+== Usage Guides
+
+Hibernate publishes multiple usage guides -
+
+link:{doc-quick-start-url}[Quick Start]::
+    Tutorial style guide for quickly getting started with Hibernate.
+link:{doc-introduction-url}[Introduction to Hibernate]::
+    High-level look at the most used Hibernate features.
+link:{doc-query-language-url}[Guide to the Hibernate Query Language]::
+    Discussion of the Hibernate Query Language.
+link:{doc-user-guide-url}[User Guide]::
+    Detailed discussion of all features of Hibernate.  More of a reference manual.
 
 
+[[logging]]
+== Logging
+
+The link:{doc-logging-url}[Logging Guide] discusses logging in Hibernate.
+
+
+[[tooling]]
 == Tooling
-* See the link:{userguide_rel_link}#tooling[Tooling Guide] for information on:
+
-** Bytecode enhancement
+See the link:{doc-user-guide-url}#tooling[Tooling Guide] for information on:
-** Static Metamodel Generation
+
-** Gradle, Maven, and Ant plugins
+* Bytecode enhancement
-** Schema management (coming soon)
+* Static Metamodel Generation
+* Gradle, Maven, and Ant plugins
+* Schema management
 
 
 == Integrator Guides
@@ -38,18 +54,45 @@ NOTE: This is still very much a work in progress. <<helping,Help>> is definitely
 * Others coming soon
 
 
-== Logging
+[[support]]
-Check out the link:{logging_rel_link}[Logging Guide] for a list of available Hibernate loggers
+== Compatibility and Support
+
+Compatibility is defined as ...
+
+Support is defined as ...
+
+By default, all parts of Hibernate are considered supported and follow the general backwards compatibility https://hibernate.org/community/compatibility-policy/[policy].
+Various things influence the levels of support and backwards compatibility to expect in regard to parts of Hibernate.
+
+[[support-internal]]
+=== Internal
+
+Internal parts of Hibernate are simply that - internal implementation details that are not supported for use by applications.
+Use of internal contracts should be avoided as they are not supported and could be removed or changed at any time.
+
+Contracts considered internal are defined in one of 2 ways:
+
+1. The Java class (interface, etc.) is defined under a package named `internal`, either directly or as a sub-package
+2. Through the use of the `@Internal` annotation.
+
+See the definitive set of link:{report-internals-url}[internals].
 
 
-== Miscellaneous
+[[support-incubating]]
-* For a list of `@Incubating` source elements, see the link:{incubating_rel_link}[incubating] list.
+=== Incubating
-* For a list of `@Internal` source elements, see the link:{internal_rel_link}[internal] list.
+
+Incubating contracts are generally new contracts which are still being actively designed, similar to
+"tech preview" features.
+Such contracts are subject to change and should be used with that understanding.
+
+See the definitive set of link:{report-incubating-url}[incubations].
+
+[[support-deprecation]]
+=== Deprecations
+
+1. `@Deprecated`
+2. `@Remove`
+
+See the definitive set of link:{report-deprecation-url}[deprecations].
 
 
-[[helping]]
-== Helping
-
-* Reporting/fixing problems.  Report any typos or inaccurate information to the
-https://hibernate.atlassian.net/browse/HHH[Hibernate ORM Jira] using the +documentation+ component.  Follow the same
-guidelines for contributing fixes and improvements as for contributing source code.

documentation/src/main/asciidoc/topical/logging/Logging.adoc

@@ -0,0 +1,19 @@
+:shared-attributes-dir: ../../shared/
+
+include::{shared-attributes-dir}/common-attributes.adoc[]
+include::{shared-attributes-dir}/url-attributes.adoc[]
+include::{shared-attributes-dir}/filesystem-attributes.adoc[]
+include::{shared-attributes-dir}/renderer-attributes.adoc[]
+
+:jboss-logging-url:
+
+[[root]]
+= Logging
+
+Hibernate uses the link:{jboss-logging-url}[JBoss Logging] library for its logging API.
+
+JBoss Logging is a logging facade, similar to SLF4J.
+
+[[logger-names]]
+== Logger Names
+

documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc

@@ -1,10 +1,14 @@
+:shared-attributes-dir: ../shared/
+
+include::{shared-attributes-dir}/common-attributes.adoc[]
+include::{shared-attributes-dir}/url-attributes.adoc[]
+include::{shared-attributes-dir}/filesystem-attributes.adoc[]
+include::{shared-attributes-dir}/renderer-attributes.adoc[]
+
 = Hibernate ORM User Guide
 :toc2:
 :toclevels: 3
 :sectanchors:
-:documentation-project-dir: ../../../..
-:root-project-dir: {documentation-project-dir}/..
-
 
 include::Preface.adoc[]
 

documentation/src/main/asciidoc/userguide/Preface.adoc

@@ -1,3 +1,6 @@
+:shared-attributes-dir: ../shared/
+include::{shared-attributes-dir}/url-attributes.adoc[]
+
 [[preface]]
 == Preface
 
@@ -14,32 +17,31 @@ However, unlike many other persistence solutions, Hibernate does not hide the po
 Hibernate may not be the best solution for data-centric applications that only use stored-procedures to implement the business logic in the database, it is most useful with object-oriented domain models and business logic in the Java-based middle-tier.
 However, Hibernate can certainly help you to remove or encapsulate vendor-specific SQL code and will help with the common task of result set translation from a tabular representation to a graph of objects.
 
+[[system-requirements]]
+=== System Requirements
+
+Hibernate {majorMinorVersion} requires at least Java 11 and JDBC 4.2.
+
+[[getting-started]]
+=== Getting Started
+
+include::{shared-attributes-dir}/background.adoc[]
+
+[TIP]
+====
+New users may want to first look at the tutorial-style link:{doc-quick-start-url}[Quick Start] guide.
+
+This User Guide is really more of a reference guide.
+For a more high-level discussion of the most used features of Hibernate, see the link:{doc-introduction-url}[Introduction to Hibernate] guide.
+
+There is also a series of link:{doc-topical-url}[topical guides] providing deep dives into various topics such as logging, compatibility and support, etc.
+====
+
+
 === Get Involved
 
 * Use Hibernate and report any bugs or issues you find. See https://hibernate.org/issuetracker[Issue Tracker] for details.
 * Try your hand at fixing some bugs or implementing enhancements. Again, see https://hibernate.org/issuetracker[Issue Tracker].
-* Engage with the community using mailing lists, forums, IRC, or other ways listed in the https://hibernate.org/community[Community section].
+* Engage with the community using the methods listed in the https://hibernate.org/community[Community section].
-* Help improve or translate this documentation. Contact us on the developer mailing list if you have interest.
+* Help improve this documentation. Contact us on the developer mailing list or Zulip if you have interest.
 * Spread the word. Let the rest of your organization know about the benefits of Hibernate.
-
-== System Requirements
-
-Hibernate 6.0 and later versions require at least Java 11 and JDBC 4.2.
-
-=== Getting Started Guide
-
-New users may want to first look through the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/quickstart/html_single/[Hibernate Getting Started Guide] for basic information as well as tutorials.
-There is also a series of https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/topical/html_single/[topical guides] providing deep dives into various topics.
-
-[NOTE]
-====
-While having a strong background in SQL is not required to use Hibernate, it certainly helps a lot because it all boils down to SQL statements.
-Probably even more important is an understanding of data modeling principles.
-You might want to consider these resources as a good starting point:
-
-* https://en.wikipedia.org/wiki/Data_modeling[Data modeling Wikipedia definition]
-* https://www.agiledata.org/essays/dataModeling101.html[Data Modeling 101]
-
-Understanding the basics of transactions and design patterns such as _Unit of Work_ (<<Bibliography.adoc#PoEAA,PoEAA>>) or _Application Transaction_ are important as well.
-These topics will be discussed in the documentation, but a prior understanding will certainly help.
-====

documentation/src/main/asciidoc/userguide/chapters/domain/associations.adoc

@@ -540,7 +540,7 @@ Neither result includes a match for "John Doe" because the inner-join filters ou
 Hibernate does support a means to refer specifically to the key column (`Person.cityName`) in a query
 using the special `fk(..)` function.  E.g.
 
-[[associations-not-found-implicit-join-example]]
+[[associations-not-found-fk-function-example]]
 .Implicit join example
 ====
 [source,java]

documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc

@@ -38,7 +38,7 @@ The semantics of a collection describes how to handle the collection, including
 
 * the collection subtype to use - `java.util.List`, `java.util.Set`, `java.util.SortedSet`, etc.
 * how to access elements of the collection
-* how to create instances of the collection - both "raw" and "wrapper" forms.  See <<collection-wrapper>>
+* how to create instances of the collection - both "raw" and "<<collection-wrapper,wrapper>>" forms.
 
 
 Hibernate supports the following semantics:

documentation/src/main/asciidoc/userguide/chapters/multitenancy/MultiTenancy.adoc

@@ -81,7 +81,7 @@ include::{example-dir-multitenancy}/AbstractMultiTenancyTest.java[tags=multitena
 For the partitioned data approach, each entity representing partitioned data must declare a field
 annotated `@TenantId`.
 
-[[multitenacy-hibernate-MultiTenantConnectionProvider-example]]
+[[multitenacy-hibernate-TenantId-example]]
 .A `@TenantId` usage example
 ====
 [source, JAVA, indent=0]