add some additional material to doc

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

@@ -351,13 +351,14 @@ logger.hibernate.name = org.hibernate.SQL
 logger.hibernate.level = debug
 ----
 
-You can make the logged SQL more readable by enabling one or both of the following settings:
+You can make the SQL logged to the console more readable by enabling formatting or highlighting.
 
-.Setting for SQL logging to the console
+.Settings for SQL logging to the console
 [cols=",2"]
 |===
 | Configuration property name | Purpose
 
+| `hibernate.show_sql` | If `true`, log SQL directly to the console
 | `hibernate.format_sql`      | If `true`, log SQL in a multiline, indented format
 | `hibernate.highlight_sql`   | If `true`, log SQL with syntax highlighting via ANSI escape codes
 |===
@@ -391,7 +392,7 @@ Please refer to the Javadoc for these interfaces for more information about the
 
 === Nationalized character data in SQL Server
 
-_By default,_ SQL Server's `char` and `varchar` types don't accommodate Unicode data. So, if you're working with SQL Server, you might need to force Hibernate to use the `nchar` and `nvarchar` types.
+_By default,_ SQL Server's `char` and `varchar` types don't accommodate Unicode data. But a Java string may contain any Unicode character. So, if you're working with SQL Server, you might need to force Hibernate to use the `nchar` and `nvarchar` column types.
 
 .Setting the use of nationalized character data
 [cols=",2"]
@@ -406,3 +407,6 @@ _By default,_ SQL Server's `char` and `varchar` types don't accommodate Unicode
 ====
 Alternatively, you can configure SQL Server to use the UTF-8 enabled collation `_UTF8`.
 ====
+
+On the other hand, if only _some_ columns store nationalized data, use the `@Nationalized` annotation to indicate fields of your entities which map these columns.
+

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

@@ -897,6 +897,26 @@ This is quite normal.
 A one-to-one association is the usual way we implement subtyping in a fully-normalized relational model.
 ====
 
+There are three annotations for mapping associations: `@ManyToOne`, `@OneToMany`, and `@ManyToMany`.
+They share some common annotation members:
+
+.Association-defining annotation members
+[cols=",4,3"]
+|===
+| Member | Interpretation | Default value
+
+| `cascade` | Persistence operations which should <<cascade,cascade>> to the associated entity (a list of ``CascadeType``s) | `{}`
+| `fetch` | Whether the association is eagerly <<association-fetching,fetched>> or may be <<proxies-and-lazy-fetching,proxied>>
+a|
+- `LAZY` for `@OneToMany` and `@ManyToMany`
+- `EAGER` for `@ManyToOne` 💀💀💀
+| `targetEntity` | The associated entity class | Determined from the attribute type declaration
+| `optional` | For `@ManyToOne` or `@OneToOne` associations, whether the association can be `null` | `true`
+| `mappedBy` | For a bidirectional association, an attribute of the associated entity which maps the association | By default, the association is assumed unidirectional
+|===
+
+We'll explain the effect of these members as we consider the various types of association mapping.
+
 Let's begin with the most common association multiplicity.
 
 [[many-to-one]]

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

@@ -652,3 +652,38 @@ InputStream bytes = book.images.getBinaryStream();
 ----
 
 Of course, the behavior here depends very much on the JDBC driver, and so we really can't promise that this is a sensible thing to do on your database.
+
+[[mapping-formulas]]
+=== Mapping to formulas
+
+Hibernate lets us map an attribute of an entity to a SQL formula involving columns of the mapped table.
+Thus, the attribute is a sort of "derived" value.
+
+.Annotations for mapping formulas
+[cols=",5"]
+|===
+| Annotation | Purpose
+
+| `@Formula` | Map an attribute to a SQL formula
+| `@JoinFormula` | Map an association to a SQL formula
+| `@DiscriminatorFormula` | Use a SQL formula as the discriminator in <<mapping-inheritance,single table inheritance>>.
+|===
+
+For example:
+
+[source,java]
+----
+@Entity
+class Order {
+    ...
+    @Column(name = "sub_total", scale=2, precision=8)
+    BigDecimal subTotal;
+
+    @Column(name = "tax", scale=4, precision=4)
+    BigDecimal taxRate;
+
+    @Formula("sub_total * (1.0 + tax)")
+    BigDecimal totalWithTax;
+    ...
+}
+----

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

@@ -394,6 +394,28 @@ List<Publisher> allpubs =
 ----
 ====
 
+[TIP]
+====
+For "reference" data, that is, for data which is expected to always be found in the second-level cache, it's a good idea to _prime_ the cache at startup.
+There's a really easy way to do this: just execute a query immediately after obtaining the
+`EntityManager` or `SessionFactory`.
+
+[source,java]
+----
+SessionFactory sf = setupHibernate(new Configuration()).buildSessionFactory();
+// prime the second-level cache
+sf.inSession(s -> {
+    s.createSelectionQuery("from Countries"))
+     .setReadOnly(true)
+     .getResultList();
+    s.createSelectionQuery("from Product where discontinued = false"))
+     .setReadOnly(true)
+     .getResultList();
+});
+
+----
+====
+
 Very occasionally, it's necessary or advantageous to control the cache explicitly, for example, to evict some data that we know to be stale.
 The `Cache` interface allows programmatic eviction of cached items.