Cleanup, (re-)organize and fix Asciidoc-based reference documentation errors.

Resolves #623.

buildSrc/src/main/java/io/spring/gradle/convention/AsciidoctorConventionPlugin.java

@@ -25,6 +25,7 @@ import java.util.List;
 import java.util.Map;
 import java.util.concurrent.Callable;
 
+import org.asciidoctor.gradle.base.log.Severity;
 import org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask;
 import org.asciidoctor.gradle.jvm.AsciidoctorJExtension;
 import org.asciidoctor.gradle.jvm.AsciidoctorJPlugin;
@@ -66,6 +67,8 @@ import org.gradle.api.tasks.Sync;
  */
 public class AsciidoctorConventionPlugin implements Plugin<Project> {
 
+	private static final boolean DEBUG_ENABLED = Boolean.getBoolean("gradle.plugins.asciidoctor.debug");
+
 	private static final String SPRING_ASCIIDOCTOR_EXTENSIONS_BLOCK_SWITCH_VERSION = "0.4.2.RELEASE";
 	private static final String SPRING_DOC_RESOURCES_VERSION = "0.2.5";
 
@@ -90,6 +93,7 @@ public class AsciidoctorConventionPlugin implements Plugin<Project> {
 
 				asciidoctorTask.dependsOn(unzipResources);
 				configureAttributes(project, asciidoctorTask);
+				configureDebugging(asciidoctorTask);
 				configureExtensions(project, asciidoctorTask);
 				configureOptions(asciidoctorTask);
 				asciidoctorTask.baseDirFollowsSourceDir();
@@ -183,6 +187,14 @@ public class AsciidoctorConventionPlugin implements Plugin<Project> {
 		asciidoctorTask.attributes(attributes);
 	}
 
+	private void configureDebugging(AbstractAsciidoctorTask asciidoctorTask) {
+
+		if (DEBUG_ENABLED) {
+			asciidoctorTask.setFailureLevel(Severity.FATAL);
+			asciidoctorTask.setLogDocuments(true);
+		}
+	}
+
 	private void configureExtensions(Project project, AbstractAsciidoctorTask asciidoctorTask) {
 
 		Configuration extensionsConfiguration = project.getConfigurations().maybeCreate("asciidoctorExtensions");

spring-data-geode-docs/spring-data-geode-docs.gradle

@@ -21,11 +21,10 @@ def versions = dependencyManagement.managedVersions
 
 asciidoctor {
 	clearSources()
+	//failureLevel 'error'
+	//logDocuments(true)
 	sources {
 		include "index.adoc"
-		include "appendix/*.adoc"
-		include "introduction/*.adoc"
-		include "reference/*.adoc"
 	}
 }
 
@@ -37,10 +36,11 @@ asciidoctorj {
 	def githubTag = snapshotBuild ? 'main' : project.version
 	def githubUrl = "$githubBaseUrl/tree/$githubTag"
 
-	attributes 'version' : project.version,
+	attributes 'version' : "$version",
 	    'version-snapshot': snapshotBuild,
 		'version-milestone': milestoneBuild,
 		'version-release': releaseBuild,
+		'data-store-name' : "Apache Geode",
 		'download-url' : "${githubBaseUrl}/archive/${githubTag}.zip",
 		'github-url': githubUrl,
 		'highlightjsdir@': "js/highlight",
@@ -56,6 +56,7 @@ asciidoctorj {
 		'docs-dir' : rootProject.projectDir.path + '/spring-data-geode-docs',
 		'docs-src-dir' : rootProject.projectDir.path + '/spring-data-geode-docs/src/main/java',
 		'docs-resources-dir' : rootProject.projectDir.path + '/spring-data-geode-docs/src/main/resources'
+
 }
 
 asciidoctorPdf {
@@ -69,6 +70,7 @@ asciidoctorPdf {
 javadoc {
 	configure(options) {
 		links = [
+			"https://docs.oracle.com/javase/8/docs/api/",
 			"https://docs.spring.io/spring/docs/current/javadoc-api/",
 			"https://docs.spring.io/spring-boot/docs/current/api/",
 			"https://docs.spring.io/spring-boot-data-geode/docs/${project.version}/api/",
@@ -91,7 +93,13 @@ processResources {
 	}
 }
 
-String resolveApacheGeodeDocVersion(String apacheGeodeVersion) {
+/*
+project.tasks.withType(Copy).forEach() {
+	it.duplicatesStrategy DuplicatesStrategy.EXCLUDE
+}
+*/
+
+static String resolveApacheGeodeDocVersion(String apacheGeodeVersion) {
 
 	def apacheGeodeDocVersion = ''
 	def index = apacheGeodeVersion.lastIndexOf(".")

spring-data-geode-docs/src/docs/asciidoc/appendix.adoc

@@ -0,0 +1,11 @@
+[[appendix]]
+= Appendix
+
+include::{spring-data-commons-include}/repository-namespace-reference.adoc[leveloffset=+1]
+include::{spring-data-commons-include}/repository-populator-namespace-reference.adoc[leveloffset=+1]
+include::{spring-data-commons-include}/repository-query-keywords-reference.adoc[leveloffset=+1]
+include::{spring-data-commons-include}/repository-query-return-types-reference.adoc[leveloffset=+1]
+
+== {sdg-name} Schemas
+* {spring-geode-schema-location}[{sdg-name} Core Schema (`gfe` XML namespace)]
+* {spring-data-geode-schema-location}[{sdg-name} Data Access Schema (`gfe-data` XML namespace)]

spring-data-geode-docs/src/docs/asciidoc/appendix/appendix-schema.adoc

@@ -1,6 +0,0 @@
-[[appendix-schema]]
-[appendix]
-= {sdg-name} Schema
-
-* {spring-geode-schema-location}[{sdg-name} Core Schema (`gfe` XML namespace)]
-* {spring-data-geode-schema-location}[{sdg-name} Data Access Schema (`gfe-data` XML namespace)]

spring-data-geode-docs/src/docs/asciidoc/index.adoc

@@ -3,23 +3,23 @@ Costin Leau; David Turanski; John Blum; Oliver Drotbohm; Jay Bryant
 :revdate: {localdate}
 :revnumber: {version}
 :toclevels: 2
-:apache-geode-version: 115
-:apache-geode-docs: https://geode.apache.org/docs/guide/{apache-geode-version}/about_geode.html
+:apache-geode-docs: https://geode.apache.org/docs/guide/{apache-geode-doc-version}/about_geode.html
 :apache-geode-javadoc: https://geode.apache.org/releases/latest/javadoc
 :apache-geode-website: https://geode.apache.org
 :apache-geode-wiki: https://cwiki.apache.org/confluence/display/GEODE
+:data-store-name-id: geode
 :data-store-name-simple: Geode
-:data-store-name-symbolic: geode
 :data-store-name: Apache {data-store-name-simple}
-:data-store-version: 1.15.0
+:data-store-version: {apache-geode-artifact-version}
+:includes-dir: reference
 :sdg-acronym: SDG
-:sdg-javadoc: https://docs.spring.io/spring-data/{data-store-name-symbolic}/docs/current/api
+:sdg-javadoc: https://docs.spring.io/spring-data/{data-store-name-id}/docs/current/api
 :sdg-name: Spring Data for {data-store-name}
 :sdg-website: https://projects.spring.io/spring-data-geode
 :spring-data-website: https://spring.io/projects/spring-data
 :spring-data-commons-docs: https://docs.spring.io/spring-data/commons/docs/current/reference
 :spring-data-commons-docs-html: {spring-data-commons-docs}/html
-:spring-data-commons-include: ../../../../spring-data-commons/src/main/asciidoc
+:spring-data-commons-include: ../../../../../spring-data-commons/src/main/asciidoc
 :spring-data-commons-javadoc: https://docs.spring.io/spring-data/commons/docs/current/api
 :spring-data-geode-schema-location: https://www.springframework.org/schema/data/geode/spring-data-geode.xsd
 :spring-data-geode-schema-namespace: https://www.springframework.org/schema/data/geode
@@ -34,6 +34,7 @@ Costin Leau; David Turanski; John Blum; Oliver Drotbohm; Jay Bryant
 :x-data-store-wiki: {apache-geode-wiki}
 ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]]
 
+
 (C) 2010-2022 The original authors.
 
 NOTE: Copies of this document may be made for your own use and for distribution to others provided that you do not
@@ -41,42 +42,34 @@ charge any fee for such copies and further provided that each copy contains this
 whether distributed in print or electronically.
 
 [[preface]]
-include::preface.adoc[]
-
-include::introduction/introduction.adoc[leveloffset=+1]
-include::introduction/requirements.adoc[leveloffset=+1]
-include::introduction/new-features.adoc[leveloffset=+1]
+include::preface.adoc[leveloffset=+1]
+include::introduction.adoc[leveloffset=+1]
+include::requirements.adoc[leveloffset=+1]
+include::new-features.adoc[leveloffset=+1]
 
 [[reference]]
-= Reference Guide
+== Reference Guide
 
-include::reference/introduction.adoc[leveloffset=+1]
-include::reference/bootstrap.adoc[leveloffset=+1]
-include::reference/bootstrap-annotations.adoc[leveloffset=+1]
-include::reference/data.adoc[leveloffset=+1]
-include::reference/serialization.adoc[leveloffset=+1]
-include::reference/mapping.adoc[leveloffset=+1]
-include::reference/repositories.adoc[leveloffset=+1]
-include::reference/function-annotations.adoc[leveloffset=+1]
-include::reference/lucene.adoc[leveloffset=+1]
-include::reference/gemfire-bootstrap.adoc[leveloffset=+1]
-include::reference/samples.adoc[leveloffset=+1]
+include::{includes-dir}/overview.adoc[leveloffset=+1]
+include::{includes-dir}/bootstrap.adoc[leveloffset=+1]
+include::{includes-dir}/bootstrap-annotations.adoc[leveloffset=+1]
+include::{includes-dir}/data.adoc[leveloffset=+1]
+include::{includes-dir}/serialization.adoc[leveloffset=+1]
+include::{includes-dir}/mapping.adoc[leveloffset=+1]
+include::{includes-dir}/repositories.adoc[leveloffset=+1]
+include::{includes-dir}/function-annotations.adoc[leveloffset=+1]
+include::{includes-dir}/lucene.adoc[leveloffset=+1]
+include::{includes-dir}/gemfire-bootstrap.adoc[leveloffset=+1]
+include::{includes-dir}/samples.adoc[leveloffset=+1]
 
 [[resources]]
-= Resources
+== Resources
 
 In addition to this reference documentation, there are a number of other resources that may help you learn
-how to use {data-store-product-name} with the _Spring Framework_. These additional, third-party resources
+how to use {data-store-name} with the _Spring Framework_. These additional, third-party resources
 are enumerated in this section.
 
 include::links.adoc[leveloffset=+1]
 
-[[appendices]]
-= Appendices
-
 :!sectnums:
-include::{spring-data-commons-include}/repository-namespace-reference.adoc[leveloffset=+1]
-include::{spring-data-commons-include}/repository-populator-namespace-reference.adoc[leveloffset=+1]
-include::{spring-data-commons-include}/repository-query-keywords-reference.adoc[leveloffset=+1]
-include::{spring-data-commons-include}/repository-query-return-types-reference.adoc[leveloffset=+1]
-include::appendix/appendix-schema.adoc[leveloffset=+1]
+include::appendix.adoc[leveloffset=+1]

spring-data-geode-docs/src/docs/asciidoc/introduction.adoc

@@ -0,0 +1,5 @@
+[[introduction]]
+== Introduction
+
+The {sdg-name} reference guide explains how to use the Spring Framework to configure and develop applications
+with {data-store-name}. It presents the basic concepts and provides numerous examples to help you get started quickly.

spring-data-geode-docs/src/docs/asciidoc/introduction/introduction.adoc

@@ -1,6 +0,0 @@
-[[introduction]]
-= Introduction
-
-The {sdg-name} reference guide explains how to use the Spring Framework
-to configure and develop applications with {data-store-name}. It presents the basic concepts
-and provides numerous examples to help you get started quickly.

spring-data-geode-docs/src/docs/asciidoc/introduction/requirements.adoc

@@ -1,5 +0,0 @@
-[[requirements]]
-= Requirements
-
-{sdg-name} requires Java 8.0, {spring-framework-website}[Spring Framework] 5
-and {x-data-store-website}[{data-store-name}] {data-store-version}.

spring-data-geode-docs/src/docs/asciidoc/links.adoc

@@ -1,4 +1,4 @@
-[[sgf-links]]
+[[spring-data-geode-links]]
 = Useful Links
 
 * https://projects.spring.io/spring-data-gemfire[{sdg-name} Project Page]

spring-data-geode-docs/src/docs/asciidoc/new-features.adoc

@@ -1,10 +1,32 @@
 [[new-features]]
-= New Features
+== New Features
 
 NOTE: As of the 1.2.0.RELEASE, this project, formerly known as Spring GemFire, has been renamed to {sdg-name}
 to reflect that it is now a module of the {spring-data-website}[Spring Data] project and built on
 {x-data-store-website}[{data-store-name}].
 
+[[new-in-2-2-0]]
+== New in the 2.2 Release
+
+* Upgraded to {data-store-name} {data-store-version}.
+* Upgraded to Spring Framework 5.2.0.RELEASE.
+* Upgraded to Spring Data Commons 2.2.0.RELEASE.
+* Add Annotation configuration support to configure and bootstrap {data-store-name} Locator applications
+using `@LocatorApplication`.
+* Added Annotation configuration support for GatewayReceivers and GatewaySenders.
+* Updated docs.
+
+[[new-in-2-1-0]]
+== New in the 2.1 Release
+
+* Upgraded to {data-store-name} {data-store-version}.
+* Upgraded to Spring Framework 5.1.0.RELEASE.
+* Upgraded to Spring Data Commons 2.1.0.RELEASE.
+* Added support for parallel cache/Region snapshots along with invoking callbacks when loading snapshots.
+* Added support for registering QueryPostProcessors to customize the OQL generated fro Repository query methods.
+* Added support for include/exclude TypeFilters in o.s.d.g.mapping.MappingPdxSerializer.
+* Updated docs.
+
 [[new-in-2-0-0]]
 == New in the 2.0 Release
 
@@ -21,25 +43,3 @@ to reflect that it is now a module of the {spring-data-website}[Spring Data] pro
 and server when using JavaConfig.
 * Added support in the Annotation configuration model for Off-Heap, Redis Adapter,
 and {data-store-name}'s new Security framework.
-
-[[new-in-2-1-0]]
-== New in the 2.1 Release
-
-* Upgraded to {data-store-name} {data-store-version}.
-* Upgraded to Spring Framework 5.1.0.RELEASE.
-* Upgraded to Spring Data Commons 2.1.0.RELEASE.
-* Added support for parallel cache/Region snapshots along with invoking callbacks when loading snapshots.
-* Added support for registering QueryPostProcessors to customize the OQL generated fro Repository query methods.
-* Added support for include/exclude TypeFilters in o.s.d.g.mapping.MappingPdxSerializer.
-* Updated docs.
-
-[[new-in-2-2-0]]
-== New in the 2.2 Release
-
-* Upgraded to {data-store-name} {data-store-version}.
-* Upgraded to Spring Framework 5.2.0.RELEASE.
-* Upgraded to Spring Data Commons 2.2.0.RELEASE.
-* Add Annotation configuration support to configure and bootstrap {data-store-name} Locator applications
-using `@LocatorApplication`.
-* Added Annotation configuration support for GatewayReceivers and GatewaySenders.
-* Updated docs.

spring-data-geode-docs/src/docs/asciidoc/preface.adoc

@@ -1,3 +1,4 @@
+[[preface]]
 = Preface
 
 {sdg-name} focuses on integrating the Spring Framework's powerful, non-invasive programming model

spring-data-geode-docs/src/docs/asciidoc/reference/bootstrap-annotations-quickstart.adoc

@@ -1,4 +1,4 @@
-[[bootstap-annotations-quickstart]]
+[[bootstrap-annotations-quickstart]]
 = Annotation-based Configuration Quick Start
 
 The following sections provide an overview to the {sdg-acronym} annotations in order to get started quickly.

spring-data-geode-docs/src/docs/asciidoc/reference/bootstrap-annotations.adoc

@@ -11,7 +11,7 @@ and as _easily_ as possible.
 Let's get started!
 
 TIP: If you would like to get started even faster, refer to
-the <<bootstap-annotations-quickstart, Quick Start>> section.
+the <<bootstrap-annotations-quickstart, Quick Start>> section.
 
 [[bootstrap-annotation-config-introduction]]
 == Introduction
@@ -974,7 +974,7 @@ and make it generally available and accessible.
 {data-store-name} organizes data in a cache into {x-data-store-docs}/basic_config/data_regions/chapter_overview.html[Regions].
 You can think of a Region as a table in a relational database. Generally, a Region should only store a single type of object,
 which makes it more conducive for building effective indexes and writing queries. We cover indexing
-<<bootstrap-annotation-config-indexes,later>>.
+<<bootstrap-annotation-config-region-indexes,later>>.
 
 Previously, {sdg-name} users needed to explicitly define and declare the Regions used by their applications to store data
 by writing very verbose Spring configuration metadata, whether using {sdg-acronym}'s `FactoryBeans` from the API
@@ -1074,7 +1074,7 @@ more sophisticated queries by declaring query methods on the repository interfac
 
 Under the hood, {sdg-name} provides an implementation of your application's repository interfaces when
 the Spring container is bootstrapped. {sdg-acronym} even implements the query methods you define so long as you follow
-the <<gemfire-repositories.executing-queries,conventions>>.
+the <<gemfire-repositories.queries.executing,conventions>>.
 
 Now, when you defined the `Book` class, you also specified the Region in which instances of `Book` are mapped (stored)
 by declaring the {sdg-name} mapping annotation, `@Region` on the entity's type. Of course, if the entity type (`Book`,
@@ -2439,6 +2439,4 @@ and `org.springframework.data.gemfire.wan.GatewaySenderFactoryBean` API classes
 The annotations were not meant to handle every situation. The annotations were meant to help you _get up and running_
 as _quickly_ and as _easily_ as possible, especially during development.
 
-We hope you will enjoy these new capabilities!
-
-include::reference/bootstrap-annotations-quickstart.adoc[leveloffset=+1]
+include::bootstrap-annotations-quickstart.adoc[leveloffset=+1]

spring-data-geode-docs/src/docs/asciidoc/reference/bootstrap.adoc

@@ -105,11 +105,11 @@ shown earlier, as the following example shows:
 <4> Bean declaration using the `gfe` namespace. Notice the lack of prefix since `gfe` is the default namespace.
 ====
 
-include::reference/data-access.adoc[leveloffset=+1]
-include::reference/cache.adoc[leveloffset=+1]
-include::reference/region.adoc[leveloffset=+1]
-include::reference/indexing.adoc[leveloffset=+1]
-include::reference/diskstore.adoc[leveloffset=+1]
-include::reference/snapshot.adoc[leveloffset=+1]
-include::reference/function.adoc[leveloffset=+1]
-include::reference/gateway.adoc[leveloffset=+1]
+include::data-access.adoc[leveloffset=+1]
+include::cache.adoc[leveloffset=+1]
+include::region.adoc[leveloffset=+1]
+include::indexing.adoc[leveloffset=+1]
+include::diskstore.adoc[leveloffset=+1]
+include::snapshot.adoc[leveloffset=+1]
+include::function.adoc[leveloffset=+1]
+include::gateway.adoc[leveloffset=+1]

spring-data-geode-docs/src/docs/asciidoc/reference/data.adoc

@@ -416,11 +416,7 @@ However, if you still want to receive transaction events "_before commit_", then
 `applicationEventPublisher.publishEvent(..)` method within your application `@Transactional` `@Service` methods.
 See the *note* above for more details.
 
-:leveloffset: +1
-
-include::reference/cq-container.adoc[]
-
-:leveloffset: -1
+include::cq-container.adoc[leveloffset=+1]
 
 [[apis:declarable]]
 == Wiring `Declarable` Components

spring-data-geode-docs/src/docs/asciidoc/reference/diskstore.adoc

@@ -1,7 +1,7 @@
 [[bootstrap:diskstore]]
 = Configuring a DiskStore
 
-{sdg-name} supports `DiskStore` configuration and creation through the `disk-store` element,
+{sdg-name} supports `DiskStore` creation and configuration through the `disk-store` element,
 as the following example shows:
 
 [source,xml]

spring-data-geode-docs/src/docs/asciidoc/reference/function-annotations.adoc

@@ -152,9 +152,9 @@ accepts an array of Strings allowing you to modify the permissions as required b
 Each resource permission is expected to be in the following format: `<RESOURCE>:<OPERATION>:[Target]:[Key]`.
 
 `RESOURCE` can be 1 of the {data-store-javadoc]/org/apache/geode/security/ResourcePermission.Resource.html[`ResourcePermission.Resource`]
-enumerated values.  `OPERATION` can be 1 of the {data-store-javadoc}/org/apache/geode/security/ResourcePermission.Operation.html[`ResourcePermission.Operation`]
+enumerated values.  `OPERATION` can be 1 of the {x-data-store-javadoc}/org/apache/geode/security/ResourcePermission.Operation.html[`ResourcePermission.Operation`]
 enumerated values.  Optionally, `Target` can be the name of a Region or 1 of the
-{data-store-javadoc}/org/apache/geode/security/ResourcePermission.Target.html[`ResourcePermission.Target`]
+{x-data-store-javadoc}/org/apache/geode/security/ResourcePermission.Target.html[`ResourcePermission.Target`]
 enumerated values. And finally, optionally, `Key` is a valid Key in the `Target` Region if specified.
 
 The `PojoFunctionWrapper` implements {data-store-name}'s `Function` interface, binds method parameters, and invokes

spring-data-geode-docs/src/docs/asciidoc/reference/overview.adoc

@@ -1,5 +1,5 @@
-[[ref-introduction]]
-= Document Structure
+[[overview]]
+= Overview & Document Structure
 
 The following chapters explain the core functionality offered by {sdg-name}:
 

spring-data-geode-docs/src/docs/asciidoc/reference/region.adoc

@@ -1141,7 +1141,7 @@ cache servers and peer data members in the distributed system and is recommended
 possible to configure the `Pool` to connect directly to one or more cache servers by using the `server` element.
 
 For a full list of options to set on the client and especially on the `Pool`, see
-the {sdg-name} schema ("`<<appendix-schema>>`") and {data-store-name}'s documentation on
+the {sdg-name} schema ("`<<appendix>>`") and {data-store-name}'s documentation on
 {x-data-store-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[Client-Server Configuration].
 
 [[bootstrap:region:client:interests]]

spring-data-geode-docs/src/docs/asciidoc/requirements.adoc

@@ -0,0 +1,5 @@
+[[requirements]]
+== Requirements
+
+{sdg-name} requires Java 8, {spring-framework-website}[Spring Framework] 5, {spring-data-website}[Spring Data Commons]
+and {x-data-store-website}[{data-store-name}] {data-store-version}.