HHH-16962 - General documentation improvements

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

(cherry picked from commit e753da1)

Author: sebersole

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

@@ -1,11 +1,12 @@
-= Hibernate ORM {majorMinorVersion} Integration Guide
-Steve Ebersole, Vlad Mihalcea
+= Hibernate ORM Integration Guide
 :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

@@ -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/credits.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/integrationguide/preface.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/Advanced.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/Configuration.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/Entities.adoc

@@ -1,24 +1,18 @@
-:pdf-theme: ../pdf/theme.yml
-:source-highlighter: rouge
-:icons: font
-:doctype: book
-:pdf-fontsdir: ../pdf/fonts
-:docsBase: https://docs.jboss.org/hibernate/orm
-:versionDocBase: {docsBase}/6.2
-:userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html
+:shared-attributes-dir: ../shared/
 
-= An introduction to Hibernate 6
-Gavin King and the Hibernate team
+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
 
-<<<
-
 include::Preface.adoc[]
 
-<<<
-
 :numbered:
 
 include::Introduction.adoc[]
@@ -28,3 +22,4 @@ include::Mapping.adoc[]
 include::Interacting.adoc[]
 include::Tuning.adoc[]
 include::Advanced.adoc[]
+include::Credits.adoc[]

documentation/src/main/asciidoc/introduction/Hibernate_Introduction.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/Interacting.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.
-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.
-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_.
+This guide is an up-to-date, high-level discussion of the current set of Hibernate features.  It does not attempt
+to cover every feature and should be used in conjunction with other documentation -
+
+- 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.
+====