compile introduction to PDF

documentation/documentation.gradle

@@ -1,7 +1,9 @@
 import org.asciidoctor.gradle.jvm.AsciidoctorTask
+import org.asciidoctor.gradle.jvm.pdf.AsciidoctorPdfTask
 
 plugins {
 	id 'org.asciidoctor.jvm.convert' version '3.3.2'
+	id 'org.asciidoctor.jvm.pdf' version '3.3.2'
 }
 
 /*
@@ -65,6 +67,11 @@ tasks.register('buildDocsForPublishing') {
 
 
 asciidoctorj {
+	modules {
+		pdf {
+			version '2.3.7'
+		}
+	}
 	attributes  icons: 'font',
 			experimental: true,
 			'source-highlighter': 'prettify',
@@ -77,6 +84,7 @@ asciidoctorj {
 // Topical Guides ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 tasks.register('renderTopicalGuides', AsciidoctorTask) { task ->
+	group = "Documentation"
 	description = 'Renders the  Topical Guides in HTML format using Asciidoctor.'
 	tasks.buildDocs.dependsOn task
 	tasks.buildDocsForPublishing.dependsOn task
@@ -96,6 +104,7 @@ tasks.register('renderTopicalGuides', AsciidoctorTask) { task ->
 // Getting Started Guides (quick starts) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 tasks.register('renderGettingStartedGuides', AsciidoctorTask) { task ->
+	group = "Documentation"
 	description = 'Renders the Getting Started Guides (quick starts) in HTML format using Asciidoctor.'
 	tasks.buildDocs.dependsOn task
 	tasks.buildDocsForPublishing.dependsOn task
@@ -125,10 +134,29 @@ tasks.register('buildTutorialZip', Zip) { task ->
 
 // Introduction ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-task renderIntroduction(type: AsciidoctorTask, group: 'Documentation') {task->
+tasks.register('renderIntroductionPdf', AsciidoctorPdfTask) {task->
+	group = "Documentation"
+	description = 'Renders the Introduction in PDF format using Asciidoctor.'
+	tasks.buildDocs.dependsOn task
+	tasks.buildDocsForPublishing.dependsOn task
+	inputs.property "hibernate-version", project.ormVersion
+
+	sourceDir = file( 'src/main/asciidoc/introduction' )
+	baseDir = file( 'src/main/asciidoc/introduction' )
+	sources {
+		include 'Hibernate_Introduction.adoc'
+	}
+	outputDir = "$buildDir/asciidoc/introduction/pdf"
+
+	attributes jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/"
+}
+
+tasks.register('renderIntroduction', AsciidoctorTask) {task->
+	group = "Documentation"
 	description = 'Renders the Introduction in HTML format using Asciidoctor.'
 	tasks.buildDocs.dependsOn task
 	tasks.buildDocsForPublishing.dependsOn task
+	inputs.property "hibernate-version", project.ormVersion
 
 	sourceDir = file( 'src/main/asciidoc/introduction' )
 	sources {
@@ -160,6 +188,7 @@ task renderIntroduction(type: AsciidoctorTask, group: 'Documentation') {task->
 // User Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 tasks.register('renderUserGuide', AsciidoctorTask) { task ->
+	group = "Documentation"
 	description = 'Renders the User Guides in HTML format using Asciidoctor.'
 	tasks.buildDocs.dependsOn task
 	tasks.buildDocsForPublishing.dependsOn task

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

@@ -202,7 +202,7 @@ On the other hand, it's very easy to use, and exposes some options that `persist
 [TIP]
 .Advanced configuration options
 ====
-Actually, the `Configuration` class is just a very simple facade for the more modern, much more powerful—but more complex—API defined in the package `org.hibernate.boot`.
+Actually, the `Configuration` class is just a very simple facade for the more modern, much more powerful—but more complex—API defined in the package `org.hibernate.boot`.
 This API is useful if you have very advanced requirements, for example, if you're writing a framework or implementing a container.
 You'll find more information in the Hibernate ORM Integration Guide, and in the package-level documentation of `org.hibernate.boot`.
 ====
@@ -218,7 +218,7 @@ Instead, we'll mention the ones you need to get started, and come back to some o
 [TIP]
 .Ya ain't gunna need 'em
 ====
-Hibernate has many—too many—switches and toggles.
+Hibernate has many—too many—switches and toggles.
 Please don't go crazy messing about with these settings; most of them are rarely needed, and many only exist to provide backward compatibility with older versions of Hibernate.
 With rare exception, the default behavior of every one of these settings was carefully chosen to be _the behavior we recommend_.
 ====
@@ -353,7 +353,7 @@ These settings can really help when troubleshooting SQL.
 
 === Minimizing repetitive mapping information
 
-The following properties are very useful for minimizing the amount of information you'll need to explicitly specify in `@Table` and `@Column` annotations, which we'll discuss below in <<mapping-entity-classes>>:
+The following properties are very useful for minimizing the amount of information you'll need to explicitly specify in `@Table` and `@Column` annotations, which we'll discuss below in <<object-relational-mapping>>:
 
 .Settings for minimizing explicit mapping information
 [cols=",2"]

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

@@ -6,7 +6,7 @@ We say that the entity _maps_ or _maps to_ the table.
 
 NOTE: Much less commonly, an entity might aggregate data from multiple tables, but we'll get to that later.
 
-An entity has _attributes_—properties or fields—which map to columns of the table.
+An entity has _attributes_—properties or fields—which map to columns of the table.
 In particular, every entity must have an _identifier_ or _id_, which maps to the primary key of the table.
 The id allows us to uniquely associate a row of the table with an instance of the Java class, at least within a given _persistence context_.
 
@@ -18,7 +18,7 @@ By providing its id to Hibernate, we may re-materialize the instance in a new pe
 Therefore, the operations `persist()` and `remove()` may be thought of as demarcating the beginning and end of the lifecycle of an entity, at least with respect to persistence.
 
 Thus, an id represents the _persistent identity_ of an entity, an identity that outlives a particular instantiation in memory.
-And this is an important difference between entity class itself and the values of its attributes—the entity has a persistent identity, and a well-defined lifecycle with respect to persistence, whereas a `String` or `List` representing one of its attribute values doesn't.
+And this is an important difference between entity class itself and the values of its attributes—the entity has a persistent identity, and a well-defined lifecycle with respect to persistence, whereas a `String` or `List` representing one of its attribute values doesn't.
 
 An entity usually has associations to other entities.
 Typically, an association between two entities maps to a foreign key in one of the database tables.
@@ -556,8 +556,8 @@ You might wonder what the difference is.
 
 Well, it's perhaps not obvious to a casual user of the JPA annotations, but they actually come in two "layers":
 
-- annotations like `@Entity`, `@Id`, and `@Basic` belong to the _logical_ layer—they specify the semantics of your Java domain model, whereas
-- annotations like `@Table` and `@Column` belong to the _mapping_ layer—they specify how elements of the domain model map to objects in the relational database.
+- annotations like `@Entity`, `@Id`, and `@Basic` belong to the _logical_ layer—they specify the semantics of your Java domain model, whereas
+- annotations like `@Table` and `@Column` belong to the _mapping_ layer—they specify how elements of the domain model map to objects in the relational database.
 
 Information may be inferred from the logical layer down to the mapping layer, but is never inferred in the opposite direction.
 
@@ -1019,7 +1019,7 @@ Here, the `Author` table has a foreign key column holding the identifier of the
 ====
 A one-to-one association often models a "type of" relationship.
 In our example, an `Author` is a type of `Person`.
-An alternative&mdash;and often more natural&mdash;way to represent "type of" relationships in Java is via <<entity-inheritance>>.
+An alternative—and often more natural—way to represent "type of" relationships in Java is via <<entity-inheritance>>.
 ====
 
 We can make this association bidirectional by adding a reference back to the `Author` in the `Person` entity:
@@ -1270,7 +1270,7 @@ The code above results in a table with three columns:
 
 Instead of a surrogate primary key, it has a composite key comprising the foreign key of `Event` and the order column.
 
-When&mdash;inevitably&mdash;we find that we need to add a fourth column to that table, our Java code must change completely.
+When—inevitably—we find that we need to add a fourth column to that table, our Java code must change completely.
 Most likely, we'll realize that we need to add a separate entity after all.
 
 There's much more we could say about "element collections", but we won't say it, because we don't want to hand you the gun that you'll shoot your foot with.

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

@@ -51,7 +51,7 @@ It quickly overtook other open source and commercial contenders to become the mo
 In 2004, Gavin and Christian joined a tiny startup called JBoss, and other early Hibernate contributors soon followed: Max Rydahl Andersen, Emmanuel Bernard, Steve Ebersole, and Sanne Grinovero.
 
 Soon after, Gavin joined the EJB 3 expert group and convinced the group to deprecate Entity Beans in favor of a brand-new persistence API modelled after Hibernate.
-Later, members of the TopLink team got involved, and the Java Persistence API evolved as a collaboration between—primarily—Sun, JBoss, Oracle, and Sybase, under the leadership of Linda Demichiel.
+Later, members of the TopLink team got involved, and the Java Persistence API evolved as a collaboration between—primarily—Sun, JBoss, Oracle, and Sybase, under the leadership of Linda Demichiel.
 
 Over the intervening two decades, _many_ talented people have contributed to the development of Hibernate.
 We're all especially grateful to Steve, who has led the project for many years, since Gavin stepped back to focus in other work.

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

@@ -1,12 +1,12 @@
 [[object-relational-mapping]]
 == Object/relational mapping
 
-Given a domain model&mdash;that is, a collection of entity classes decorated with all the fancy annotations we <<entities-summary,just met>> in the previous chapter&mdash;Hibernate will happily go away and infer a complete relational schema, and even <<automatic-schema-export,export it to your database>> if you ask politely.
+Given a domain model—that is, a collection of entity classes decorated with all the fancy annotations we <<entities-summary,just met>> in the previous chapter—Hibernate will happily go away and infer a complete relational schema, and even <<automatic-schema-export,export it to your database>> if you ask politely.
 
 The resulting schema will be entirely sane and reasonable, though if you look closely, you'll find some flaws.
 For example, every `VARCHAR` column will have the same length, `VARCHAR(255)`.
 
-But the process I just described&mdash;which we call _top down_ mapping&mdash;simply doesn't fit the most common scenario for the use of O/R mapping.
+But the process I just described—which we call _top down_ mapping—simply doesn't fit the most common scenario for the use of O/R mapping.
 It's only rarely that the Java classes precede the relational schema.
 Usually, _we already have a relational schema_, and we're constructing our domain model around the schema.
 This is called _bottom up_ mapping.
@@ -16,7 +16,7 @@ This is called _bottom up_ mapping.
 ====
 Developers often refer to a pre-existing relational database as "legacy" data.
 That's perhaps a bad word to use, conjuring images of bad old "legacy apps" written in COBOL or something.
-But it's not "legacy" data&mdash;it's just your data.
+But it's not "legacy" data—it's just your data.
 And it's valuable.
 So learning to work with "legacy" data is important.
 ====
@@ -439,8 +439,8 @@ class Book {
 
 The `@PrimaryKeyJoinColumn` is a special-purpose annotation for mapping:
 
-- the primary key column of a `@SecondaryTable`&mdash;which is also a foreign key referencing the primary table, or
-- the primary key column of the primary table mapped by a subclass in a `JOINED` inheritance hierarchy&mdash;which is also a foreign key referencing the primary table mapped by the root entity.
+- the primary key column of a `@SecondaryTable`—which is also a foreign key referencing the primary table, or
+- the primary key column of the primary table mapped by a subclass in a `JOINED` inheritance hierarchy—which is also a foreign key referencing the primary table mapped by the root entity.
 
 .`@PrimaryKeyJoinColumn` annotation members
 [cols=",8"]
@@ -489,7 +489,7 @@ class Book {
 === Column lengths and adaptive column types
 
 Hibernate automatically adjusts the column type used in generated DDL based on the column length specified by the `@Column` annotation.
-So we don't usually need to explicitly specify that a column should be of type `TEXT` or `CLOB`&mdash;or worry about the parade of `TINYTEXT`, `MEDIUMTEXT`, `TEXT`, `LONGTEXT` types on MySQL&mdash;because Hibernate will automatically select one of those types if required to accommodate a string of the `length` we specify.
+So we don't usually need to explicitly specify that a column should be of type `TEXT` or `CLOB`—or worry about the parade of `TINYTEXT`, `MEDIUMTEXT`, `TEXT`, `LONGTEXT` types on MySQL—because Hibernate will automatically select one of those types if required to accommodate a string of the `length` we specify.
 
 The constant values defined in the class `org.hibernate.Length` are very helpful here: