Docs - add an execution that generates multiple HTMLs; add index page…

…; make sure links are generated conditionally based on whether its single or multi HTML.

docs/reference/pom.xml

@@ -59,6 +59,7 @@
                         </goals>
                         <configuration>
                             <backend>pdf</backend>
+                            <sourceDocumentName>Weld_-_JSR-299_Reference_Implementation.asciidoc</sourceDocumentName>
                             <outputDirectory>${doc.output.directory}/en-US/pdf</outputDirectory>
                             <outputFile>${pdf.name}</outputFile>
                         </configuration>
@@ -69,21 +70,37 @@
                         <goals>
                             <goal>process-asciidoc</goal>
                         </goals>
+                        <configuration>
+                            <backend>html5</backend>
+                            <sourceDocumentName>Weld_-_JSR-299_Reference_Implementation.asciidoc</sourceDocumentName>
+                            <outputDirectory>${doc.output.directory}/en-US/html_single</outputDirectory>
+                            <outputFile>${html.name}</outputFile>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>output-html-chunked</id>
+                        <phase>generate-resources</phase>
+                        <goals>
+                            <goal>process-asciidoc</goal>
+                        </goals>
                         <configuration>
                             <backend>html5</backend>
                             <attributes>
                                 <docinfo>shared</docinfo>
+                                <!-- Auto-generate TOC for each HTML -->
+                                <toc>left</toc>
+                                <toclevels>3</toclevels>
+                                <!-- Triggers conditional addition of link to index page -->
+                                <generate-index-link></generate-index-link>
                             </attributes>
-                            <outputDirectory>${doc.output.directory}/en-US/html_single</outputDirectory>
-                            <outputFile>${html.name}</outputFile>
+                            <outputDirectory>${doc.output.directory}/en-US/html</outputDirectory>
                         </configuration>
                     </execution>
                 </executions>
 
                 <configuration>
                     <doctype>book</doctype>
                     <sourceDirectory>${basedir}/src/main/asciidoc</sourceDirectory>
-                    <sourceDocumentName>Weld_-_JSR-299_Reference_Implementation.asciidoc</sourceDocumentName>
                     <templateEngine>slim</templateEngine>
                     <headerFooter>true</headerFooter>
                     <attributes>

docs/reference/src/main/asciidoc/beans.asciidoc

@@ -1,3 +1,7 @@
+ifdef::generate-index-link[]
+link:index.html[Weld {weldVersion} - CDI Reference Implementation]
+endif::[]
+
 [[beanscdi]]
 == More about beans
 
@@ -49,7 +53,10 @@ We can replace one bean with another different bean that implements the
 same interface and has a different lifecycle (a different scope) without
 affecting the other bean implementation. In fact, CDI defines a simple
 facility for overriding bean implementations at deployment time, as we
-will see in <<alternatives>>.
+will see in
+ifndef::generate-index-link[<<alternatives>>]
+ifdef::generate-index-link[link:injection.html#alternatives[Alternatives]]
+.
 
 Note that not all clients of a bean are beans themselves. Other objects
 such as servlets or message-driven beans—which are by nature not
@@ -121,7 +128,9 @@ NOTE: The bean types of a session bean include local interfaces and the bean
 class local view (if any). EJB remote interfaces are not considered bean
 types of a session bean. You can't inject an EJB using its remote
 interface unless you define a _resource_, which we'll meet in
-<<resources>>.
+ifndef::generate-index-link[<<resources>>]
+ifdef::generate-index-link[link:resources.html[Java EE component environment resources]]
+.
 
 Bean types may be restricted to an explicit set by annotating the bean
 with the `@Typed` annotation and listing the classes that should be bean
@@ -202,7 +211,10 @@ it has the default qualifier, `@Default`.
 That's not quite the end of the story. CDI also defines a simple
 _resolution rule_ that helps the container decide what to do if there is
 more than one bean that satisfies a particular contract. We'll get into
-the details in <<injection>>.
+the details in
+ifndef::generate-index-link[<<injection>>]
+ifdef::generate-index-link[link:injection.html[Dependency injection and programmatic lookup]]
+.
 
 ==== Scope
 
@@ -234,7 +246,10 @@ special scope called the _dependent pseudo-scope_. Beans with this scope
 live to serve the object into which they were injected, which means
 their lifecycle is bound to the lifecycle of that object.
 
-We'll talk more about scopes in <<scopescontexts>>.
+We'll talk more about scopes in
+ifndef::generate-index-link[<<scopescontexts>>]
+ifdef::generate-index-link[link:scopescontexts.html[Scopes and contexts]]
+.
 
 ==== EL name
 
@@ -301,7 +316,10 @@ Different modules can specify that they use different alternatives.
 The other way to enable an alternative is to annotate the bean with
 `@Priority` annotation. This will enable it globally.
 
-We cover alternatives in more detail in <<alternatives>>.
+We cover alternatives in more detail in
+ifndef::generate-index-link[<<alternatives>>]
+ifdef::generate-index-link[link:injection.html#alternatives[Alternatives]]
+.
 
 ==== Interceptor binding types
 
@@ -370,7 +388,14 @@ also where we specify the interceptor ordering.
 Better still, we can use `@Priority` annotation to enable the interceptor
 and define it's ordering at the same time.
 
-We'll discuss interceptors, and their cousins, decorators, in <<interceptors>> and <<decorators>>.
+We'll discuss interceptors, and their cousins, decorators, in
+ifndef::generate-index-link[<<interceptors>>]
+ifdef::generate-index-link[link:interceptors.html[Interceptors]]
+and
+ifndef::generate-index-link[<<decorators>>]
+ifdef::generate-index-link[link:decorators.html[Decorators]]
+.
+<<interceptors>> and <<decorators>>.
 
 === What kinds of classes are beans?
 
@@ -590,7 +615,10 @@ injection.
 }
 ------------------------------------------
 
-We'll talk much more about producer methods in <<producer_methods>>.
+We'll talk much more about producer methods in
+ifndef::generate-index-link[<<producer_methods>>]
+ifdef::generate-index-link[link:producermethods.html[Producer methods]]
+.
 
 ==== Producer fields
 
@@ -616,5 +644,7 @@ A producer field is really just a shortcut that lets us avoid writing a
 useless getter method. However, in addition to convenience, producer
 fields serve a specific purpose as an adaptor for Java EE component
 environment injection, but to learn more about that, you'll have to wait
-until <<resources>>. Because we can't wait to get
-to work on some examples.
+until
+ifndef::generate-index-link[<<resources>>]
+ifdef::generate-index-link[link:resources.html[Java EE component environment resources]]
+. Because we can't wait to get to work on some examples.

docs/reference/src/main/asciidoc/configure.asciidoc

@@ -1,3 +1,7 @@
+ifdef::generate-index-link[]
+link:index.html[Weld {weldVersion} - CDI Reference Implementation]
+endif::[]
+
 [[configure]]
 == Configuration
 
@@ -31,7 +35,10 @@ This mode is not enabled by default. It can be enabled using the following confi
 |`org.jboss.weld.construction.relaxed` |false (true in weld-se)|If set to `true`, then requirements on bean constructors are relaxed.
 |=======================================================================
 
-Note that relaxed construction is enabled by default in <<weld-se,Weld SE>>.
+Note that relaxed construction is enabled by default in
+ifndef::generate-index-link[<<weld-se,Weld SE>>]
+ifdef::generate-index-link[link:environments.html#weld-se[Weld SE]]
+.
 
 ==== Concurrent deployment configuration
 
@@ -188,7 +195,10 @@ This optimization is used to reduce the HTTP session replication overhead. Howev
 |`org.jboss.weld.serialization.beanIdentifierIndexOptimization` |true (false in weld-servlet)|If set to `true`, the optimization is enabled.
 |=======================================================================
 
-NOTE: This optimization is disabled by default in <<weld-servlet,Servlet containers>>.
+NOTE: This optimization is disabled by default in
+ifndef::generate-index-link[<<weld-servlet,Servlet containers>>]
+ifdef::generate-index-link[link:environments.html#weld-servlet[Servlet containers]]
+.
 
 ==== Rolling upgrades ID delimiter
 
@@ -220,19 +230,43 @@ WARNING: Bean archive identifiers are provided by integrators. Therefore, the ab
 [[config-dev-mode]]
 ==== Development Mode
 
-Some features of the <<devmode,development mode>> may have negative impact on the performance and/or functionality of the application. The following configuration properties allow to tune or disable these features, e.g. to specify the set of components which will be monitored.
+Some features of the
+ifndef::generate-index-link[<<devmode,development mode>>]
+ifdef::generate-index-link[link:developmentmode.html[development mode]]
+may have negative impact on the performance and/or functionality of the application. The following configuration properties allow to tune or disable these features, e.g. to specify the set of components which will be monitored.
 
 .Supported configuration properties
 [cols="1,1,1,2",options="header"]
 |=======================================================================
 |Configuration key|Tool|Default value |Description
-|`org.jboss.weld.probe.invocationMonitor.excludeType`|<<probe,Probe>>|'' |A regular expression. If a non-empty string and the base type for an AnnotatedType or a declaring type for an AnnotatedMember matches this pattern the type is excluded from monitoring.
-|`org.jboss.weld.probe.invocationMonitor.skipJavaBeanProperties`|<<probe,Probe>>|'true' |If set to `true`, the JavaBean accessor methods are not monitored.
-|`org.jboss.weld.probe.eventMonitor.excludeType`|<<probe,Probe>>|'' |A regular expression. If a non-empty string  and the runtime class of the event object matches this pattern the event is excluded from monitoring.
-|`org.jboss.weld.probe.eventMonitor.containerLifecycleEvents`|<<probe,Probe>>|'false'|If set to `true` all the container lifecycle events are monitored during bootstrap.
-|`org.jboss.weld.probe.embedInfoSnippet`|<<probe,Probe>>|'true' | If set to `true` an informative HTML snippet will be added to every HTTP response with Content-Type of value `text/html`.
-|`org.jboss.weld.probe.jmxSupport`|<<probe,Probe>>|'false' | If set to `true` one or more MBean components may be registered so that it's possible to use JMX to access the Probe development tool data.
-|`org.jboss.weld.probe.exportDataAfterDeployment`|<<probe,Probe>>|'' | If a non-empty string the Probe data will be automatically exported after deployment validation. The value represents the path of the directory where to export the data file.
+|`org.jboss.weld.probe.invocationMonitor.excludeType`|
+ifndef::generate-index-link[<<probe,Probe>>]
+ifdef::generate-index-link[link:developmentmode.html#probe[Probe]]
+|'' |A regular expression. If a non-empty string and the base type for an AnnotatedType or a declaring type for an AnnotatedMember matches this pattern the type is excluded from monitoring.
+|`org.jboss.weld.probe.invocationMonitor.skipJavaBeanProperties`|
+ifndef::generate-index-link[<<probe,Probe>>]
+ifdef::generate-index-link[link:developmentmode.html#probe[Probe]]
+|'true' |If set to `true`, the JavaBean accessor methods are not monitored.
+|`org.jboss.weld.probe.eventMonitor.excludeType`|
+ifndef::generate-index-link[<<probe,Probe>>]
+ifdef::generate-index-link[link:developmentmode.html#probe[Probe]]
+|'' |A regular expression. If a non-empty string  and the runtime class of the event object matches this pattern the event is excluded from monitoring.
+|`org.jboss.weld.probe.eventMonitor.containerLifecycleEvents`|
+ifndef::generate-index-link[<<probe,Probe>>]
+ifdef::generate-index-link[link:developmentmode.html#probe[Probe]]
+|'false'|If set to `true` all the container lifecycle events are monitored during bootstrap.
+|`org.jboss.weld.probe.embedInfoSnippet`|
+ifndef::generate-index-link[<<probe,Probe>>]
+ifdef::generate-index-link[link:developmentmode.html#probe[Probe]]
+|'true' | If set to `true` an informative HTML snippet will be added to every HTTP response with Content-Type of value `text/html`.
+|`org.jboss.weld.probe.jmxSupport`|
+ifndef::generate-index-link[<<probe,Probe>>]
+ifdef::generate-index-link[link:developmentmode.html#probe[Probe]]
+|'false' | If set to `true` one or more MBean components may be registered so that it's possible to use JMX to access the Probe development tool data.
+|`org.jboss.weld.probe.exportDataAfterDeployment`|
+ifndef::generate-index-link[<<probe,Probe>>]
+ifdef::generate-index-link[link:developmentmode.html#probe[Probe]]
+|'' | If a non-empty string the Probe data will be automatically exported after deployment validation. The value represents the path of the directory where to export the data file.
 |=======================================================================
 
 TIP: To disable the monitoring entirely set `org.jboss.weld.probe.invocationMonitor.excludeType` and `org.jboss.weld.probe.eventMonitor.excludeType` properties to `.*`.
@@ -279,7 +313,10 @@ The functionality is implemented as a built-in portable extension processing all
 CDI applications consist of user-defined beans implementing the business logic, but also beans coming from libraries (e.g. DeltaSpike) and integrations (e.g. various Java EE technologies - JSF, Bean Validation, Batch).
 Most applications actually use only a small part of the beans provided by libraries and integrations.
 Still, Weld has to retain the metadata for all the beans in memory which can be considerably vast footprint, depending on the application.
-If <<allow-optimized-cleanup>> is allowed, Weld can remove _unused_ beans after bootstrap.
+If
+ifndef::generate-index-link[<<allow-optimized-cleanup>>]
+ifdef::generate-index-link[link:ri-spi.html#allow-optimized-cleanup[Optimized cleanup after bootstrap]]
+is allowed, Weld can remove _unused_ beans after bootstrap.
 
 An _unused_ bean:
 
@@ -291,7 +328,10 @@ An _unused_ bean:
 * does not declare a producer which is eligible for injection to any injection point,
 * is not eligible for injection into any `Instance<X>` injection point.
 
-TIP: If you run <<probe>> and list all the beans in your application, you will almost certainly notice some of them coming from 3rd party libraries which you never use (marked with a trash icon). Those are candidates for _unused beans_ as you can be sure you are not using them.
+TIP: If you run
+ifndef::generate-index-link[<<probe>>]
+ifdef::generate-index-link[link:developmentmode.html#probe[Probe]]
+and list all the beans in your application, you will almost certainly notice some of them coming from 3rd party libraries which you never use (marked with a trash icon). Those are candidates for _unused beans_ as you can be sure you are not using them.
 
 NOTE: As usual, there is a trade-off between memory consumption and bootstrap time. The results may vary depending on the application, but you should always expect (most probably negligible) increase of the bootstrap time.
 
@@ -331,7 +371,10 @@ public class MyExternalConfiguration implements ExternalConfiguration {
 }
 --------------------------------------------------------------------------
 
-Bear in mind that because `ExternalConfiguration` extends a `Service` it is required that any custom external configuration implementation is explicitly registered. See <<_the_weld_spi>> for more information.
+Bear in mind that because `ExternalConfiguration` extends a `Service` it is required that any custom external configuration implementation is explicitly registered. See
+ifndef::generate-index-link[<<_the_weld_spi>>]
+ifdef::generate-index-link[link:ri-spi.html#_the_weld_spi[The Weld SPI]]
+for more information.
 
 Last but not least external configuration is considered a source with the lowest priority which means that the properties specified there can be overriden by other sources such as system properties.
 For information on supported configuration keys, see <<_weld_configuration>>. Also note that entries with unsupported properties will be ignored while invalid property values will lead
@@ -352,7 +395,10 @@ CDI specification does not support regular expression patterns and `!`
 character to invert the activation condition.
 
 All the configuration is done in the `beans.xml` file. For more
-information see <<packaging-and-deployment>>.
+information see
+ifndef::generate-index-link[<<packaging-and-deployment>>]
+ifdef::generate-index-link[link:ee.html#packaging-and-deployment[Packaging and deployment]]
+.
 
 [source.XML, xml]
 ------------------------------------------------------------------------------------------------------

docs/reference/src/main/asciidoc/contexts.asciidoc

@@ -1,3 +1,7 @@
+ifdef::generate-index-link[]
+link:index.html[Weld {weldVersion} - CDI Reference Implementation]
+endif::[]
+
 [[contexts]]
 == Context Management
 

docs/reference/src/main/asciidoc/decorators.asciidoc

@@ -1,3 +1,7 @@
+ifdef::generate-index-link[]
+link:index.html[Weld {weldVersion} - CDI Reference Implementation]
+endif::[]
+
 [[decorators]]
 == Decorators
 

docs/reference/src/main/asciidoc/developmentmode.asciidoc

@@ -1,3 +1,7 @@
+ifdef::generate-index-link[]
+link:index.html[Weld {weldVersion} - CDI Reference Implementation]
+endif::[]
+
 [[devmode]]
 == Development Mode
 
@@ -72,10 +76,16 @@ You should see the following log message during initialization of your applicati
 This tool allows you to inspect the application CDI components at runtime.
 There is a default UI - HTML client (single-page application), which is only available in web applications.
 Just point your browser to `protocol://host:port/webappContextPath/weld-probe`, e.g. `http://localhost:8080/weld-numberguess/weld-probe`.
-However, it's also posible to obtain the JSON data through the REST API, eventually (if <<config-dev-mode,JMX support is enabled>>) through the MXBean of name `org.jboss.weld.probe:type=JsonData,context=ID` where ID should be replaced with an idenfitier of an application.
+However, it's also posible to obtain the JSON data through the REST API, eventually (if
+ifndef::generate-index-link[<<config-dev-mode,JMX support is enabled>>]
+ifdef::generate-index-link[link:configure.html#config-dev-mode[JMX support is enabled]]
+) through the MXBean of name `org.jboss.weld.probe:type=JsonData,context=ID` where ID should be replaced with an idenfitier of an application.
 Right now, Probe integration is provided for WildFly, Tomcat and Jetty (Weld Servlet), and Weld SE.
 
-TIP: There are some configuration properties which allow to tune or disable Probe features, e.g. to restrict the set of components which will be monitored. See also <<config-dev-mode>>.
+TIP: There are some configuration properties which allow to tune or disable Probe features, e.g. to restrict the set of components which will be monitored. See also
+ifndef::generate-index-link[<<config-dev-mode>>]
+ifdef::generate-index-link[link:configure.html#config-dev-mode[Development Mode]]
+.
 
 
 [[validation-report]]
@@ -84,7 +94,10 @@ TIP: There are some configuration properties which allow to tune or disable Prob
 If a deployment validation fails and the development mode is enabled a simple HTML report is generated.
 The report contains a lot of useful information such as Weld version, list of enabled beans, list of bean archives, Weld configuration, etc.
 By default, the report is generated to the user's current working directory, ie. `user.dir`.
-However, it is also possible to specify a path to the target directory using the `org.jboss.weld.probe.exportDataAfterDeployment` configuration property - see also <<config-dev-mode>>.
+However, it is also possible to specify a path to the target directory using the `org.jboss.weld.probe.exportDataAfterDeployment` configuration property - see also
+ifndef::generate-index-link[<<config-dev-mode>>]
+ifdef::generate-index-link[link:configure.html#config-dev-mode[Development Mode]]
+.
 
 You should see a similar log message which contains the path to the report file:
 

docs/reference/src/main/asciidoc/ee.asciidoc

@@ -1,3 +1,7 @@
+ifdef::generate-index-link[]
+link:index.html[Weld {weldVersion} - CDI Reference Implementation]
+endif::[]
+
 [[ee]]
 == Java EE integration