minor edits, flat structure of some chapters
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
index 0f603d9..d4f255a 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
@@ -30,9 +30,9 @@
</dependency>
----
-==== Gradle Projects
+==== Gradle
-To add Cayenne to your Maven project, include `cayenne-server` module:
+To add Cayenne to your Gradle project, include `cayenne-server` module:
[source, Groovy,subs="verbatim,attributes"]
----
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3.adoc
index 700d072..274789d 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3.adoc
@@ -12,9 +12,11 @@
// the specific language governing permissions and limitations under the
// License.
+[#rop]
== Cayenne Framework - Remote Object Persistence
include::part3/rop.adoc[]
+
include::part3/ropDeployment.adoc[]
// TODO: add content to these files:
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5.adoc
index 75dae27..a6ac8d7 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5.adoc
@@ -12,7 +12,7 @@
// the specific language governing permissions and limitations under the
// License.
-== Cayenne Additional Modules
+== Additional Modules
include::part5/cacheInvalidation.adoc[]
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/apacheVelocity.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/apacheVelocity.adoc
index 5d27406..a542340 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/apacheVelocity.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/apacheVelocity.adoc
@@ -14,16 +14,12 @@
include::../var.adoc[]
-[[ext-velocity]]
-=== Apache Velocity extension
+[#ext-velocity]
+=== Apache Velocity Extension
-==== Description
+Enables usage of full featured Apache Velocity templates in `SQLSelect` / `SQLExec` queries.
-This module enables usage of full featured Apache Velocity templates in `org.apache.cayenne.query.SQLTemplate` queries.
-
-==== Including in a project
-
-===== Maven
+==== Maven
[source, XML,subs="verbatim,attributes"]
----
@@ -34,7 +30,7 @@
</dependency>
----
-===== Gradle
+==== Gradle
[source, Groovy, subs="verbatim,attributes"]
----
@@ -43,11 +39,16 @@
==== Usage
-This module doesn't require any additional setup.
+This module doesn't require any additional setup. In addition of directives mentioned in <<directives,this chapter>>,
+this module also adds `#chain` and `#chunk` directives.
-In addition of directives mentioned in <<directives,this chapter>>, this module enables `#chain` and `#chunk` directives.
-
-`#chain` and `#chunk` directives are used for conditional inclusion of SQL code. They are used together with `#chain` wrapping multiple `#chunks`. A chunk evaluates its parameter expression and if it is NULL suppresses rendering of the enclosed SQL block. A chain renders its prefix and its chunks joined by the operator. If all the chunks are suppressed, the chain itself is suppressed. This allows to work with otherwise hard to script SQL semantics. E.g. a WHERE clause can contain multiple conditions joined with AND or OR. Application code would like to exclude a condition if its right-hand parameter is not present (similar to Expression pruning discussed above). If all conditions are excluded, the entire WHERE clause should be excluded. chain/chunk allows to do that.
+`#chain` and `#chunk` directives are used for conditional inclusion of SQL code. They are used together with `#chain`
+wrapping multiple `#chunks`. A chunk evaluates its parameter expression and if it is NULL suppresses rendering of the
+enclosed SQL block. A chain renders its prefix and its chunks joined by the operator. If all the chunks are suppressed,
+the chain itself is suppressed. This allows to work with otherwise hard to script SQL semantics. E.g. a WHERE clause
+can contain multiple conditions joined with AND or OR. Application code would like to exclude a condition if its
+right-hand parameter is not present (similar to Expression pruning discussed above). If all conditions are excluded,
+the entire WHERE clause should be excluded. chain/chunk allows to do that.
Semantics:
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
index 1ac32b8..49203d2 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
@@ -14,16 +14,12 @@
include::../var.adoc[]
-[[ext-cache-invalidation]]
-=== Cache invalidation extension
-
-==== Description
+[#ext-cache-invalidation]
+=== Cache Invalidation Extension
Cache invalidation module is an extension that allows to define cache invalidation policy programmatically.
-==== Including in a project
-
-===== Maven
+==== Maven
[source, XML,subs="verbatim,attributes"]
----
@@ -34,7 +30,7 @@
</dependency>
----
-===== Gradle
+==== Gradle
[source, Groovy,subs="verbatim,attributes"]
----
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cayenneOsgi.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cayenneOsgi.adoc
index 8454016..042a87a 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cayenneOsgi.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cayenneOsgi.adoc
@@ -14,15 +14,12 @@
include::../var.adoc[]
+[#ext-osgi]
=== Cayenne OSGI extension
-==== Description
+Helps to bootstrap Cayenne in OSGi environment.
-This module helps to bootstrap Cayenne in OSGi environment.
-
-==== Including in a project
-
-===== Maven
+==== Maven
[source, XML,subs="verbatim,attributes"]
----
@@ -33,7 +30,7 @@
</dependency>
----
-===== Gradle
+==== Gradle
[source, Groovy,subs="verbatim,attributes"]
----
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cayenneRopServer.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cayenneRopServer.adoc
index d360fef..bde6693 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cayenneRopServer.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cayenneRopServer.adoc
@@ -14,13 +14,10 @@
include::../var.adoc[]
-=== Cayenne Rop Server extension
+[#ext-rop]
+=== Cayenne ROP Server Extension
-==== Description
-
-This module creates services for the server side of an xref:introduction-to-rop[ROP] application.
-
-==== Including in a project
+Creates services for the server side of an <<rop,ROP>> application.
===== Maven
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cayenneWeb.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cayenneWeb.adoc
index a70528d..d1a2c8a 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cayenneWeb.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cayenneWeb.adoc
@@ -14,15 +14,12 @@
include::../var.adoc[]
-=== Cayenne Web extension
+[#ext-web]
+=== Cayenne Web Extension
-==== Description
+Provides basic utilities to bootstrap Cayenne service inside web application.
-This module provides basic utilities to bootstrap Cayenne service inside web application.
-
-==== Including in a project
-
-===== Maven
+==== Maven
[source, XML,subs="verbatim,attributes"]
----
@@ -33,7 +30,7 @@
</dependency>
----
-===== Gradle
+==== Gradle
[source, Groovy,subs="verbatim,attributes"]
----
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc
index 2a58280..2c66ffa 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc
@@ -17,13 +17,9 @@
[[ext-commit-log]]
=== Commit log extension
-==== Description
-
The goal of this module is to capture commit changes and present them to interested parties in an easy-to-process format.
-==== Including in a project
-
-===== Maven
+==== Maven
[source, XML,subs="verbatim,attributes"]
----
@@ -34,7 +30,7 @@
</dependency>
----
-===== Gradle
+==== Gradle
[source, Groovy,subs="verbatim,attributes"]
----
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
index c702064..f686199 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
@@ -17,13 +17,9 @@
[[ext-crypto]]
=== Crypto extension
-==== Description
-
Crypto module allows encrypt and decrypt values stored in DB transparently to your Java app.
-==== Including in a project
-
-===== Maven
+==== Maven
[source, XML,subs="verbatim,attributes"]
----
@@ -34,7 +30,7 @@
</dependency>
----
-===== Gradle
+==== Gradle
[source, Groovy,subs="verbatim,attributes"]
----
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc
index 70d1848..c16d06a 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc
@@ -17,13 +17,9 @@
[[ext-jcache]]
=== JCache integration
-==== Description
+Allows to integrate any JCache (JSR 107) compatible caching provider with Cayenne.
-This module allows to integrate any JCache (JSR 107) compatible caching provider with Cayenne.
-
-==== Including in a project
-
-===== Maven
+==== Maven
[source, XML,subs="verbatim,attributes"]
----
@@ -34,7 +30,7 @@
</dependency>
----
-===== Gradle
+==== Gradle
[source, Groovy,subs="verbatim,attributes"]
----
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/projectCompatibility.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/projectCompatibility.adoc
index da07b1d..02af779 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/projectCompatibility.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/projectCompatibility.adoc
@@ -17,15 +17,13 @@
[[ext-project-compatibility]]
=== Project compatibility extension
-==== Description
-
-Since version 4.1 Cayenne doesn't allow to load project XML files from previous versions as this can lead to unexpected errors in runtime. This module allows to use project files from older versions performing their upgrade on the fly (without modifying files). This can be useful when using Cayenne models from third-party libraries in your app.
+Since version 4.1 Cayenne doesn't allow to load project XML files from previous versions as this can lead to unexpected
+errors in runtime. This module allows to use project files from older versions performing their upgrade on the fly
+(without modifying files). This can be useful when using Cayenne models from third-party libraries in your app.
NOTE: You should prefer explicit project upgrade via Cayenne Modeler.
-==== Including in a project
-
-===== Maven
+==== Maven
[source, XML,subs="verbatim,attributes"]
----
@@ -36,7 +34,7 @@
</dependency>
----
-===== Gradle
+==== Gradle
[source, Groovy,subs="verbatim,attributes"]
----
