add a TIP and whitespace in some code fragments

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

@@ -997,6 +997,7 @@ class Book {
 
     @ManyToOne(fetch=LAZY)
     Publisher publisher;
+
     ...
 }
 ----
@@ -1018,6 +1019,13 @@ Most of the time, we would like to be able to easily navigate our associations i
 We do need a way to get the `Publisher` of a given `Book`, but we would also like to be able to obtain all the ``Book``s belonging to a given publisher.
 
 To make this association bidirectional, we need to add a collection-valued attribute to the `Publisher` class, and annotate it `@OneToMany`.
+
+[NOTE]
+====
+Hibernate needs to <<proxies-and-lazy-fetching,proxy>> unfetched associations at runtime.
+Therefore, the many-valued side must be declared using an interface type like `Set` or `List`, and never using a concrete type like `HashSet` or `ArrayList`.
+====
+
 To indicate clearly that this is a bidirectional association, and to reuse any mapping information already specified in the `Book` entity, we must use the `mappedBy` annotation member to refer back to `Book.publisher`.
 
 [source,java]
@@ -1029,6 +1037,7 @@ class Publisher {
 
     @OneToMany(mappedBy="publisher")
     Set<Book> books;
+
     ...
 }
 ----
@@ -1045,22 +1054,22 @@ Set<Book> books;
 ----
 We're going to use this approach for the rest of the Introduction.
 
+To modify a bidirectional association, we must change the _owning side_.
+
 [[bidirectional-problem]]
 [WARNING]
 // .To modify a bidirectional association, you must change the _owning side_!
 ====
-To modify a bidirectional association, you must change the _owning side_!
-
 Changes made to the unowned side of an association are never synchronized to the database.
 If we desire to change an association in the database, we must change it from the owning side.
 Here, we must set `Book.publisher`.
 
 In fact, it's often necessary to change _both sides_ of a bidirectional association.
 For example, if the collection `Publisher.books` was stored in the second-level cache, we must also modify the collection, to ensure that the second-level cache remains synchronized with the database.
-
-That said, it's not a hard requirement to update the unowned side, at least if you're sure you know what you're doing.
 ====
 
+That said, it's _not_ a hard requirement to update the unowned side, at least if you're sure you know what you're doing.
+
 [TIP]
 // .Unidirectional `@OneToMany`?
 ====

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

@@ -222,6 +222,7 @@ The `@Table` annotation can do more than just specify a name:
 | `indexes` | One or more `@Index` annotations each declaring an index
 |===
 
+[%unbreakable]
 [TIP]
 // .If you don't need to, don't hardcode the schema and catalog
 ====
@@ -250,6 +251,11 @@ The `@SecondaryTable` annotation is even more interesting:
 | `foreignKey` | An `@ForeignKey` annotation specifying the name of the `FOREIGN KEY` constraint on the ``@PrimaryKeyJoinColumn``s
 |===
 
+[TIP]
+====
+Using `@SecondaryTable` on a subclass in a `SINGLE_TABLE` entity inheritance hierarchy gives us a sort of mix of `SINGLE_TABLE` with `JOINED` inheritance.
+====
+
 [[join-table-mappings]]
 === Mapping associations to tables
 
@@ -261,9 +267,11 @@ This annotation is usually used with `@ManyToMany` associations:
 @Entity
 class Book {
     ...
+
     @ManyToMany
     @JoinTable(name="BooksAuthors")
     Set<Author> authors;
+
     ...
 }
 ----
@@ -275,9 +283,11 @@ But it's even possible to use it to map a `@ManyToOne` or `@OneToOne` associatio
 @Entity
 class Book {
     ...
+
     @ManyToOne(fetch=LAZY)
     @JoinTable(name="BookPublisher")
     Publisher publisher;
+
     ...
 }
 ----
@@ -289,9 +299,11 @@ Here, there should be a `UNIQUE` constraint on one of the columns of the associa
 @Entity
 class Author {
     ...
+
     @OneToOne(optional=false, fetch=LAZY)
     @JoinTable(name="AuthorPerson")
     Person author;
+
     ...
 }
 ----
@@ -421,10 +433,12 @@ Here we see how to use `@JoinColumn` to define a `@ManyToOne` association mappin
 @Table(name="Items")
 class Item {
     ...
+
     @ManyToOne(optional=false)  // implies nullable=false
     @JoinColumn(name = "bookIsbn", referencedColumnName = "isbn",  // a reference to a non-PK column
                 foreignKey = @ForeignKey(name="ItemsToBooksBySsn")) // supply a name for the FK constraint
     Book book;
+
     ...
 }
 ----
@@ -453,10 +467,12 @@ For composite foreign keys we might have multiple `@JoinColumn` annotations:
 @Table(name="Items")
 class Item {
     ...
+
     @ManyToOne(optional=false)
     @JoinColumn(name = "bookIsbn", referencedColumnName = "isbn")
     @JoinColumn(name = "bookPrinting", referencedColumnName = "printing")
     Book book;
+
     ...
 }
 ----
@@ -469,11 +485,13 @@ If we need to specify the `@ForeignKey`, this starts to get a bit messy:
 @Table(name="Items")
 class Item {
     ...
+
     @ManyToOne(optional=false)
     @JoinColumns(value = {@JoinColumn(name = "bookIsbn", referencedColumnName = "isbn"),
                           @JoinColumn(name = "bookPrinting", referencedColumnName = "printing")},
                  foreignKey = @ForeignKey(name="ItemsToBooksBySsn"))
     Book book;
+
     ...
 }
 ----