Add Multi-Page HTML Reference

- to avoid having to load the whole document
- provide a link to the single page version for browser search

* Fix cross-document links.

Links need to be qualified with the containing file name for the
multi-page html doc.

Author: garyrussell

build.gradle

@@ -6,6 +6,7 @@ buildscript {
 	dependencies {
 		classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion"
 		classpath "org.jetbrains.kotlin:kotlin-allopen:$kotlinVersion"
+		classpath "org.asciidoctor:asciidoctor-gradle-plugin:1.5.6"
 		classpath 'org.asciidoctor:asciidoctorj-pdf:1.5.0-alpha.16'
 	}
 }
@@ -819,6 +820,12 @@ project("spring-integration-bom") {
 	}
 }
 
+apply plugin: "org.asciidoctor.convert"
+
+asciidoctorj {
+	version = '1.5.5'
+}
+
 configurations {
 	docs
 }
@@ -836,33 +843,52 @@ task prepareAsciidocBuild(type: Sync) {
 	into "$buildDir/asciidoc"
 }
 
-asciidoctor {
-	dependsOn 'prepareAsciidocBuild'
+task('makePDF', type: org.asciidoctor.gradle.AsciidoctorTask) {
+	dependsOn prepareAsciidocBuild
+	backends 'pdf'
 	sourceDir "$buildDir/asciidoc"
 	sources {
-		include 'index.adoc'
+		include 'index-single.adoc'
 	}
+	options doctype: 'book', eruby: 'erubis'
+	logDocuments = true
+	attributes 'icons': 'font',
+		'sectanchors': '',
+		'sectnums': '',
+		'toc': '',
+		'source-highlighter' : 'coderay',
+		revnumber: project.version
+}
+
+asciidoctor {
+	dependsOn makePDF
+	backends 'html5'
+	sourceDir "$buildDir/asciidoc"
 	resources {
 		from(sourceDir) {
-			include 'images/*', 'css/*', 'js/**'
+			include 'images/*', 'css/**', 'js/**'
 		}
 	}
-	backends = ['html5', 'pdf']
 	options doctype: 'book', eruby: 'erubis'
-	attributes  'icons': 'font',
-			'idprefix': '',
-			'idseparator': '-',
-			docinfo: 'shared',
-			sectanchors: '',
-			sectnums: '',
-			stylesdir: 'css/',
-			stylesheet: 'spring.css',
-			'linkcss': true,
-			'source-highlighter=highlight.js',
-			'highlightjsdir=js/highlight',
-			'highlightjs-theme=atom-one-dark-reasonable',
-			'project-version': project.version,
-			'allow-uri-read': ''
+	logDocuments = true
+	attributes 'docinfo': 'shared',
+		// use provided stylesheet
+		stylesdir: "css/",
+		stylesheet: 'spring.css',
+		'linkcss': true,
+		'icons': 'font',
+		'sectanchors': '',
+		// use provided highlighter
+		'source-highlighter=highlight.js',
+		'highlightjsdir=js/highlight',
+		'highlightjs-theme=atom-one-dark-reasonable',
+		'idprefix': '',
+		'idseparator': '-',
+		'spring-version': project.version,
+		'allow-uri-read': '',
+		'toc': 'left',
+		'toclevbels': '4',
+		revnumber: project.version
 }
 
 task reference(dependsOn: asciidoctor) {
@@ -953,8 +979,9 @@ task docsZip(type: Zip, dependsOn: reference) {
 	    }
 
 	    from ('build/asciidoc/pdf') {
-		     include 'index.pdf'
-		     into 'reference/pdf'
+			include "index-single.pdf"
+			rename  'index-single.pdf', 'spring-integration-reference.pdf'
+			into 'reference/pdf'
 	    }
 }
 

src/reference/asciidoc/aggregator.adoc

@@ -108,7 +108,7 @@ It is done only if the message group release result is not a message or collecti
 In that case a target `MessageGroupProcessor` is responsible for the `MessageBuilder.popSequenceDetails()` call while building those messages.
 This functionality can be controlled by a new `popSequence` `boolean` property, so the `MessageBuilder.popSequenceDetails()` can be disabled in some scenarios when correlation details have not been populated by the standard splitter.
 This property, essentially, undoes what has been done by the nearest upstream `applySequence = true` in the `AbstractMessageSplitter`.
-See <<splitter>> for more information.
+See <<./splitter.adoc#splitter,Splitter>> for more information.
 
 [[agg-message-collection]]
 IMPORTANT: The `SimpleMessageGroup.getMessages()` method returns an `unmodifiableCollection`.
@@ -223,7 +223,7 @@ The 4.3 release changed the default `Collection` for messages in a `SimpleMessag
 This was expensive when removing individual messages from large groups (an O(n) linear scan was required).
 Although the hash set is generally much faster to remove, it can be expensive for large messages, because the hash has to be calculated on both inserts and removes.
 If you have messages that are expensive to hash, consider using some other collection type.
-As discussed in <<message-group-factory>>, a `SimpleMessageGroupFactory` is provided so that you can select the `Collection` that best suits your needs.
+As discussed in <<./message-store.adoc#message-group-factory,Using `MessageGroupFactory`>>, a `SimpleMessageGroupFactory` is provided so that you can select the `Collection` that best suits your needs.
 You can also provide your own factory implementation to create some other `Collection<Message<?>>`.
 
 The following example shows how to configure an aggregator with the previous implementation and a `SimpleSequenceSizeReleaseStrategy`:
@@ -324,7 +324,7 @@ Of course, the first solution above does not apply in this case.
 [[aggregator-java-dsl]]
 ==== Configuring an Aggregator in Java DSL
 
-See <<java-dsl-aggregators>> for how to configure an aggregator in Java DSL.
+See <<./dsl.adoc#java-dsl-aggregators,Aggregators and Resequencers>> for how to configure an aggregator in Java DSL.
 
 [[aggregator-xml]]
 ===== Configuring an Aggregator with XML
@@ -399,7 +399,7 @@ Optional.
 <6> A reference to a `MessageGroupStore` used to store groups of messages under their correlation key until they are complete.
 Optional.
 By default, it is a volatile in-memory store.
-See <<message-store>> for more information.
+See <<./message-store.adoc#message-store,Message Store>> for more information.
 <7> The order of this aggregator when more than one handle is subscribed to the same `DirectChannel` (use for load-balancing purposes).
 Optional.
 <8> Indicates that expired messages should be aggregated and sent to the 'output-channel' or 'replyChannel' once their containing `MessageGroup` is expired (see https://docs.spring.io/spring-integration/api/org/springframework/integration/store/MessageGroupStore.html#expireMessageGroups-long[`MessageGroupStore.expireMessageGroups(long)`]).
@@ -457,7 +457,7 @@ Note that the actual time to expire an empty group is also affected by the reape
 It used to obtain a `Lock` based on the `groupId` for concurrent operations on the `MessageGroup`.
 By default, an internal `DefaultLockRegistry` is used.
 Use of a distributed `LockRegistry`, such as the `ZookeeperLockRegistry`, ensures only one instance of the aggregator can operate on a group concurrently.
-See <<redis-lock-registry>>, <<gemfire-lock-registry>>, and <<zk-lock-registry>> for more information.
+See <<./redis.adoc#redis-lock-registry,Redis Lock Registry>>, <<./gemfire.adoc#gemfire-lock-registry,Gemfire Lock Registry>>, and <<./zookeeper.adoc#zk-lock-registry,Zookeeper Lock Registry>> for more information.
 <21> A timeout (in milliseconds) to force the `MessageGroup` complete when the `ReleaseStrategy` does not release the group when the current message arrives.
 This attribute provides a built-in time-based release strategy for the aggregator when there is a need to emit a partial result (or discard the group) if a new message does not arrive for the `MessageGroup` within the timeout.
 When a new message arrives at the aggregator, any existing `ScheduledFuture<?>` for its `MessageGroup` is canceled.
@@ -750,7 +750,7 @@ public MessageHandler aggregator(MessageGroupStore jdbcMessageGroupStore) {
 ----
 ====
 
-See <<aggregator-api>> and <<annotations_on_beans>> for more information.
+See <<aggregator-api>> and <<./configuration.adoc#annotations_on_beans,Annotations on `@Bean` Methods>> for more information.
 
 NOTE: Starting with version 4.2, the `AggregatorFactoryBean` is available to simplify Java configuration for the `AggregatingMessageHandler`.
 
@@ -863,5 +863,5 @@ Messages with the same correlation key are stored in the same message group.
 Some `MessageStore` implementations allow using the same physical resources, by partitioning the data.
 For example, the `JdbcMessageStore` has a `region` property, and the `MongoDbMessageStore` has a `collectionName` property.
 
-For more information about the `MessageStore` interface and its implementations, see <<message-store>>.
+For more information about the `MessageStore` interface and its implementations, see <<./message-store.adoc#message-store,Message Store>>.
 =====

src/reference/asciidoc/amqp.adoc

@@ -294,7 +294,7 @@ The default `BatchingStrategy` is the `SimpleBatchingStrategy`, but this can be
 ==== Overview
 
 Version 5.0.1 introduced a polled channel adapter, letting you fetch individual messages on demand -- for example, with a `MessageSourcePollingTemplate` or a poller.
-See <<deferred-acks-message-source>> for more information.
+See <<./polling-consumer.adoc#deferred-acks-message-source,Deferred Acknowledgment Pollable Message Source>> for more information.
 
 It does not currently support XML configuration.
 
@@ -1036,7 +1036,7 @@ When `true` (the default), the connection is established (if it does not already
 it) when the first message is sent.
 ====
 
-See also <<async-service-activator>> for more information.
+See also <<./service-activator.adoc#async-service-activator,Asynchronous Service Activator>> for more information.
 
 [IMPORTANT]
 .RabbitTemplate
@@ -1492,7 +1492,7 @@ This is because the template "`borrows`" a channel from the cache for each send
 One solution is to start a transaction before the splitter, but transactions are expensive in RabbitMQ and can reduce performance several hundred fold.
 
 To solve this problem in a more efficient manner, starting with version 5.1, Spring Integration provides the `BoundRabbitChannelAdvice` which is a `HandleMessageAdvice`.
-See <<handle-message-advice>>.
+See <<./handler-advice.adoc#handle-message-advice,Handling Message Advice>>.
 When applied before the splitter, it ensures that all downstream operations are performed on the same channel and, optionally, can wait until publisher confirmations for all sent messages are received (if the connection factory is configured for confirmations).
 The following example shows how to use `BoundRabbitChannelAdvice`:
 

src/reference/asciidoc/chain.adoc

@@ -121,7 +121,7 @@ In this case, it is 'somethingChain$child#1'.
 Note, this transformer is not registered as a bean within the application context, so it does not get a `beanName`.
 However its `componentName` has a value that is useful for logging and other purposes.
 
-The `id` attribute for `<chain>` elements lets them be eligible for <<jmx-mbean-exporter,JMX export>>, and they are trackable in the <<message-history,message history>>.
+The `id` attribute for `<chain>` elements lets them be eligible for <<./jmx.adoc#jmx-mbean-exporter,,JMX export>>, and they are trackable in the <<./message-history.adoc#message-history,,message history>>.
 You can access them from the `BeanFactory` by using the appropriate bean name, as discussed earlier.
 
 TIP: It is useful to provide an explicit `id` attribute on `<chain>` elements to simplify the identification of sub-components in logs and to provide access to them from the `BeanFactory` etc.

src/reference/asciidoc/changes-1.0-2.0.adoc

@@ -18,7 +18,7 @@ This guide includes many samples.
 ===== Conversion Service and Converter
 
 You can now benefit from the conversion service support provided with Spring while configuring many Spring Integration components, such as a https://www.enterpriseintegrationpatterns.com/DatatypeChannel.html[Datatype channel].
-See <<channel-implementations>> and <<service-activator>>.
+See <<./channel.adoc#channel-implementations,Message Channel Implementations>> and <<./service-activator.adoc#service-activator,Service Activator>>.
 Also, the SpEL support mentioned in the previous point also relies upon the conversion service.
 Therefore, you can register converters once and take advantage of them anywhere you use SpEL expressions.
 
@@ -30,14 +30,14 @@ Spring Integration (which uses a lot of scheduling) now builds upon these.
 In fact, Spring Integration 1.0 had originally defined some of the components (such as `CronTrigger`) that have now been migrated into Spring 3.0's core API.
 Now you can benefit from reusing the same components within the entire application context (not just Spring Integration configuration).
 We also greatly simplified configuration of Spring Integration pollers by providing attributes for directly configuring rates, delays, cron expressions, and trigger references.
-See <<channel-adapter>> for sample configurations.
+See <<./channel-adapter.adoc#channel-adapter,Channel Adapter>> for sample configurations.
 
 [[rest-support]]
 ===== `RestTemplate` and `HttpMessageConverter`
 
 Our outbound HTTP adapters now delegate to Spring's `RestTemplate` for executing the HTTP request and handling its response.
 This also means that you can reuse any custom `HttpMessageConverter` implementations.
-See <<http-outbound>> for more details.
+See <<./http.adoc#http-outbound,HTTP Outbound Components>> for more details.
 
 [[new-eip]]
 ==== Enterprise Integration Pattern Additions
@@ -48,30 +48,30 @@ Also in 2.0, we have added support for even more of the patterns described in Ho
 ===== Message History
 
 We now provide support for the https://www.enterpriseintegrationpatterns.com/MessageHistory.html[message history] pattern, letting you keep track of all traversed components, including the name of each channel and endpoint as well as the timestamp of that traversal.
-See <<message-history>> for more details.
+See <<./message-history.adoc#message-history,Message History>> for more details.
 
 [[new-message-store]]
 ===== Message Store
 
 We now provide support for the https://www.enterpriseintegrationpatterns.com/MessageStore.html[message store] pattern.
 The message store provides a strategy for persisting messages on behalf of any process whose scope extends beyond a single transaction, such as the aggregator and the resequencer.
 Many sections of this guide include samples of how to use a message store, as it affects several areas of Spring Integration.
-See <<message-store>>, <<claim-check>>, <<channel>>, <<aggregator>>, <<jdbc>>`", and <<resequencer>> for more details.
+See <<./message-store.adoc#message-store,Message Store>>, <<./claim-check.adoc#claim-check,Claim Check>>, <<./channel.adoc#channel,Message Channels>>, <<./aggregator.adoc#aggregator,Aggregator>>, <<./jdbc.adoc#jdbc,JDBC Support>>`", and <<./resequencer.adoc#resequencer,Resequencer>> for more details.
 
 [[new-claim-check]]
 ===== Claim Check
 
 We have added an implementation of the https://www.enterpriseintegrationpatterns.com/StoreInLibrary.html[claim check] pattern.
 The idea behind the claim check pattern is that you can exchange a message payload for a "`claim ticket`".
 This lets you reduce bandwidth and avoid potential security issues when sending messages across channels.
-See <<claim-check>> for more details.
+See <<./claim-check.adoc#claim-check,Claim Check>> for more details.
 
 [[new-control-bus]]
 ===== Control Bus
 
 We have provided implementations of the https://www.enterpriseintegrationpatterns.com/ControlBus.html[control bus] pattern, which lets you use messaging to manage and monitor endpoints and channels.
 The implementations include both a SpEL-based approach and one that runs Groovy scripts.
-See <<control-bus>> and <<groovy-control-bus>> for more details.
+See <<./control-bus.adoc#control-bus,Control Bus>> and <<./groovy.adoc#groovy-control-bus,Control Bus>> for more details.
 
 [[new-adapters]]
 ==== New Channel Adapters and Gateways
@@ -82,7 +82,7 @@ We have added several new channel adapters and messaging gateways in Spring Inte
 ===== TCP and UDP Adapters
 
 We have added channel adapters for receiving and sending messages over the TCP and UDP internet protocols.
-See <<ip>> for more details.
+See <<./ip.adoc#ip,TCP and UDP Support>> for more details.
 See also the following blog: https://spring.io/blog/2010/03/29/using-udp-and-tcp-adapters-in-spring-integration-2-0-m3/["`Using UDP and TCP Adapters in Spring Integration 2.0 M3`"].
 
 [[new-twitter]]
@@ -96,25 +96,25 @@ See https://github.com/spring-projects/spring-integration-extensions/tree/master
 ===== XMPP Adapters
 
 The new XMPP adapters support both chat messages and presence events.
-See <<xmpp>> for more details.
+See <<./xmpp.adoc#xmpp,XMPP Support>> for more details.
 
 [[new-ftp]]
 ===== FTP and FTPS Adapters
 
 Inbound and outbound file transfer support over FTP and FTPS is now available.
-See <<ftp>> for more details.
+See <<./ftp.adoc#ftp,FTP/FTPS Adapters>> for more details.
 
 [[new-sftp]]
 ===== SFTP Adapters
 
 Inbound and outbound file transfer support over SFTP is now available.
-See <<sftp>> for more details.
+See <<./sftp.adoc#sftp,SFTP Adapters>> for more details.
 
 [[new-feed]]
 ===== Feed Adapters
 
 We have also added channel adapters for receiving news feeds (ATOM and RSS).
-See <<feed>> for more details.
+See <<./feed.adoc#feed,Feed Adapter>> for more details.
 
 [[new-other]]
 ==== Other Additions
@@ -125,33 +125,33 @@ This section describes them.
 ===== Groovy Support
 
 Spring Integration 2.0 added Groovy support, letting you use the Groovy scripting language to provide integration and business logic.
-See <<groovy>> for more details.
+See <<./groovy.adoc#groovy,Groovy support>> for more details.
 
 [[new-map-transformer]]
 ===== Map Transformers
 
 These symmetrical transformers convert payload objects to and from `Map` objects.
-See <<transformer>> for more details.
+See <<./transformer.adoc#transformer,Transformer>> for more details.
 
 [[new-json-transformer]]
 ===== JSON Transformers
 
 These symmetrical transformers convert payload objects to and from JSON.
-See <<transformer>> for more details.
+See <<./transformer.adoc#transformer,Transformer>> for more details.
 
 [[new-serialize-transformer]]
 ===== Serialization Transformers
 
 These symmetrical transformers convert payload objects to and from byte arrays.
 They also support the serializer and deserializer strategy interfaces that Spring 3.0.5 added.
-See <<transformer>> for more details.
+See <<./transformer.adoc#transformer,Transformer>> for more details.
 
 [[new-refactoring]]
 ==== Framework Refactoring
 
 The core API went through some significant refactoring to make it simpler and more usable.
 Although we anticipate that the impact to developers should be minimal, you should read through this document to find what was changed.
-Specifically, you should read <<dynamic-routers>>, <<gateway>>, <<http-outbound>>, <<message>>, and <<aggregator>>.
+Specifically, you should read <<./router.adoc#dynamic-routers,Dynamic Routers>>, <<./gateway.adoc#gateway,Messaging Gateways>>, <<./http.adoc#http-outbound,HTTP Outbound Components>>, <<./message.adoc#message,Message>>, and <<./aggregator.adoc#aggregator,Aggregator>>.
 If you directly depend on some of the core components (`Message`, `MessageHeaders`, `MessageChannel`, `MessageBuilder`, and others), you need to update any import statements.
 We restructured some packaging to provide the flexibility we needed for extending the domain model while avoiding any cyclical dependencies (it is a policy of the framework to avoid such "`tangles`").