misc updates to Short Guide before release

Author: gavinking

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

@@ -397,13 +397,14 @@ properties:
 | Configuration property name                                | Purpose
 
 | `jakarta.persistence.schema-generation.database.action`
-a| * If `drop-and-create`, first drop the schema and then export tables, sequences, and constraints
-* If `create`, export tables, sequences, and constraints, without attempting to drop them first
-* If `create-drop`, drop the schema and recreate it on `SessionFactory` startup
-Additionally, drop the schema on `SessionFactory` shutdown
+a| * If `drop-and-create`, first drop the schema, then export tables, sequences, and constraints, and then populate initial data
+* If `create`, export tables, sequences, and constraints, without attempting to drop them first, and then populate initial data
+* If `create-drop`, drop the schema and recreate it on `SessionFactory` startup;
+additionally, drop the schema on `SessionFactory` shutdown
 * If `drop`, drop the schema on `SessionFactory` shutdown
 * If `validate`, validate the database schema without changing it
-* If `update`, only export what's missing in the schema
+* If `update`, only export what's missing in the schema, and alter incorrect column types
+* If `populate`, only populate initial data
 
 | `jakarta.persistence.create-database-schemas`
 | (Optional) If `true`, automatically create schemas and catalogs
@@ -478,7 +479,7 @@ logger.jdbc-extract.level=trace
 
 ----
 
-But with this approach we miss out on the pretty highlighting.
+SQL logging respects the settings `hibernate.format_sql` and `hibernate.highlight_sql`, so we don't miss out on the pretty formatting and highlighting.
 
 [[minimizing]]
 === Minimizing repetitive mapping information

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

@@ -71,7 +71,7 @@ When XML-based mappings are used, the `<entity>` element is used to declare an e
 Since the `orm.xml` mapping file format defined by the JPA specification was modelled closely on the annotation-based mappings, it's usually easy to go back and forth between the two options.
 ****
 
-We won't have much more to say about XML-based mappings in this Introduction, since it's not our preferred way to do things.
+We won't have much more to say about XML-based mappings in this Short Guide, since it's not our preferred way to do things.
 
 ."Dynamic" models
 ****
@@ -1189,7 +1189,7 @@ bit more type safe:
 @OneToMany(mappedBy=Book_.PUBLISHER)  // get used to doing it this way!
 Set<Book> books;
 ----
-We're going to use this approach for the rest of the Introduction.
+We're going to use this approach for the rest of the Short Guide.
 
 To modify a bidirectional association, we must change the _owning side_.
 

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

@@ -695,7 +695,7 @@ Hibernate features three complementary ways to write queries:
 
 :hql: {doc-user-guide-url}#query-language
 
-A full discussion of the query language would require almost as much text as the rest of this Introduction.
+A full discussion of the query language would require almost as much text as the rest of this Short Guide.
 Fortunately, HQL is already described in exhaustive (and exhausting) detail in {doc-query-language-url}[_A Guide to Hibernate Query Language_].
 It doesn't make sense to repeat that information here.
 // The query language is discussed in great detail below in <<query-language>>.

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

@@ -161,7 +161,7 @@ We're going to <<organizing-persistence,come back soon>> to the thorny question
 
 Before we get deeper into the weeds, we'll quickly present a basic example program that will help you get started if you don't already have Hibernate integrated into your project.
 
-We begin with a simple gradle build file:
+We begin with a simple https://gradle.org[Gradle] build file:
 
 [[build-gradle]]
 [source,groovy,subs="attributes+"]
@@ -203,7 +203,7 @@ dependencies {
 
 Only the first of these dependencies is absolutely _required_ to run Hibernate.
 
-Next, we'll add a logging configuration file for log4j:
+Next, we'll add a logging configuration file for https://logging.apache.org/log4j/[log4j]:
 
 [source,properties]
 .`log4j2.properties`
@@ -212,17 +212,28 @@ rootLogger.level = info
 rootLogger.appenderRefs = console
 rootLogger.appenderRef.console.ref = console
 
+# SQL statements (set level=debug to enable)
 logger.hibernate.name = org.hibernate.SQL
 logger.hibernate.level = info
-
+# JDBC parameter binding (set level=trace to enable)
+logger.jdbc-bind.name=org.hibernate.orm.jdbc.bind
+logger.jdbc-bind.level=info
+# JDBC result set extraction (set level=trace to enable)
+logger.jdbc-extract.name=org.hibernate.orm.jdbc.extract
+logger.jdbc-extract.level=info
+# JDBC batching (set level=trace to enable)
+logger.batch.name=org.hibernate.orm.jdbc.batch
+logger.batch.level=info
+
+# direct log output to the console
 appender.console.name = console
 appender.console.type = Console
 appender.console.layout.type = PatternLayout
 appender.console.layout.pattern = %highlight{[%p]} %m%n
 ----
 
 Now we need some Java code.
-We begin with our _entity class_:
+We begin with our <<domain-model,_entity class_>>:
 
 [[book]]
 [source,java]
@@ -251,9 +262,9 @@ class Book {
 }
 ----
 
-Finally, let's see code which configures and instantiates Hibernate and asks it to persist and query the entity.
+Finally, let's see code which <<configuration,configures>> and instantiates Hibernate and asks it to <<interacting,persist and query>> the entity.
 Don't worry if this makes no sense at all right now.
-It's the job of this Introduction to make all this crystal clear.
+It's the job of the rest of this Short Guide to make all this crystal clear.
 
 [[main-hibernate]]
 [source,java]