From 6402a3fc2dd316d51a043eb908993f2569716f08 Mon Sep 17 00:00:00 2001
From: Adam Scott <aescott@us.ibm.com>
Date: Fri, 5 Aug 2016 11:48:23 -0400
Subject: [PATCH] Added clickable links for intenral references, issue #5

---
 .../asciidoc/batch_programming_model.adoc     | 10 +-
 .../src/main/asciidoc/batch_runtime_spec.adoc | 24 ++---
 .../src/main/asciidoc/domain_language.adoc    |  4 +-
 specification/src/main/asciidoc/forward.adoc  |  2 +-
 .../asciidoc/job_specification_language.adoc  | 94 +++++++++----------
 .../src/main/asciidoc/jsr352_1_0_a.adoc       |  4 +-
 6 files changed, 69 insertions(+), 69 deletions(-)

diff --git a/specification/src/main/asciidoc/batch_programming_model.adoc b/specification/src/main/asciidoc/batch_programming_model.adoc
index 91094aa..9ec0c4d 100644
--- a/specification/src/main/asciidoc/batch_programming_model.adoc
+++ b/specification/src/main/asciidoc/batch_programming_model.adoc
@@ -1132,9 +1132,9 @@ model artifacts, then have values passed to them when a job is
 initiated. Batch properties are string values.
 
 Note batch properties are visible only in the scope in which they are
-defined (see Section 9.3.2). However batch properties values can be
+defined (see Section xref:_scope_of_property_definitions_for_batchproperty[9.3.2]). However batch properties values can be
 formed from other properties according to Job XML Substitution Rules.
-See section 8.8 for further information on substitution.
+See section xref:_job_xml_substitution[8.8] for further information on substitution.
 
 ==== @BatchProperty
 
@@ -1212,7 +1212,7 @@ corresponding property element with a matching name is specified in the
 JSL in the scope that applies to the batch artifact in question. If the
 JSL property value resolves to the empty string (either explicitly set
 to the empty string literal or resolving to an empty string via property
-substitution – see section 8.8), no assignment is made and the resulting
+substitution – see section xref:_job_xml_substitution[8.8]), no assignment is made and the resulting
 value is undefined by the batch specification. The resulting value might
 simply be the Java default value, however using various dependency
 injection technologies may produce different results. The resultant
@@ -1422,7 +1422,7 @@ See section 10.9.4 for details on the PartitionPlan result value type.
 The PartitionMapper, when defined, is invoked upon every execution,
 including restarted executions. For a full discussion of the behavior on
 restart, including how to override particular details of the
-PartitionPlan built by the previous execution, see section 10.8.5.
+PartitionPlan built by the previous execution, see section xref:_batchruntime[10.8.5].
 
 ==== PartitionReducer Interface
 
@@ -1562,7 +1562,7 @@ PartitionReducer {
 A partition collector provides a way to send data from individual
 partitions to a single point of control running on the parent thread.
 The PartitionAnalyzer is used to receive and process this data. See
-section 9.5.4 for further information about the PartitionAnalyzer. The
+section xref:_partitionanalyzer_interface[9.5.4] for further information about the PartitionAnalyzer. The
 PartitionCollector interface may be used to implement an
 PartitionCollector batch artifact:
 
diff --git a/specification/src/main/asciidoc/batch_runtime_spec.adoc b/specification/src/main/asciidoc/batch_runtime_spec.adoc
index 1d83eff..7a1bdea 100644
--- a/specification/src/main/asciidoc/batch_runtime_spec.adoc
+++ b/specification/src/main/asciidoc/batch_runtime_spec.adoc
@@ -47,7 +47,7 @@ particular step within a job execution.
 |=======================================================================
 
 Note instanceId, executionId, and stepExecutionId are all globally
-unique values within a job repository. See section 7.4 for explanation
+unique values within a job repository. See section xref:_job_repository[7.4] for explanation
 of job repository.
 
 === JobOperator
@@ -83,7 +83,7 @@ an instance or null. +
 +
 The `batch.xml` file is packaged by the developer with the application under the '`META-INF`' directory ('`WEB-INF/classes/META-INF`' for .war files). +
 +
-See 10.7.1 for more about the `batch.xml` file.
+See xref:_job_parameters_on_restart[10.7.1] for more about the `batch.xml` file.
 
 3.  Thread Context Class Loader +
 +
@@ -110,7 +110,7 @@ from the `META-INF/batch-jobs` directory. +
 +
 Job XML documents may be packaged by the developer with the application under the '`META-INF/batch-jobs`' directory ('`WEB-INF/classes/META-INF`/batch-jobs' for .war files). +
 +
-See 10.7.2 for more about the `META-INF/batch-jobs`.
+See xref:_job_xml_substitution_during_restart[10.7.2] for more about the `META-INF/batch-jobs`.
 
 === Application Packaging Model
 The batch artifacts that comprise a batch application requiring no
@@ -123,7 +123,7 @@ method).
 
 ==== `META-INF/batch.xml`
 
-A batch application may use the archive loader (see section 10.5) to
+A batch application may use the archive loader (see section xref:_job_xml_loading[10.5]) to
 load batch artifacts. The application can direct artifact loading by
 supplying an optional `batch.xml` file. The `batch.xml` file must be stored
 under the `META-INF` directory. For .jar files it is the standard `META-INF`
@@ -149,7 +149,7 @@ batch artifact implementation.
 Notes:
 
 1. If an implementation-specific loader is used (see
-10.5) any artifact it loads takes precedence over artifacts specified in `batch.xml`.
+xref:_job_xml_loading[10.5]) any artifact it loads takes precedence over artifacts specified in `batch.xml`.
 
 2. Use of `batch.xml` to load batch artifacts requires the
 availability of a zero-argument constructor (either a default
@@ -158,7 +158,7 @@ constructor ).
 
 ==== `META-INF/batch-jobs`
 
-A batch application may use the archive loader (see section 10.6) to
+A batch application may use the archive loader (see section xref:_application_packaging_model[10.6]) to
 load Job XML documents. The application does this by storing the Job XML
 documents under the `META-INF/batch-jobs` directory. For .jar files the
 batch-jobs directory goes under the standard `META-INF` directory. For
@@ -175,7 +175,7 @@ specified on the JobOperator.start command.
 |.xml |Specifies required file type of a Job XML file under
 `META-INF/batch-jobs`.
 |=======================================================================
-Note if an implementation-specific loader (see 10.6) loads a Job XML
+Note if an implementation-specific loader (see xref:_application_packaging_model[10.6]) loads a Job XML
 document that document takes precedence over documents stored under
 `META-INF/batch-jobs`.
 
@@ -233,12 +233,12 @@ provided below.
 Upon restart, the job is processed as follows:
 
 [arabic]
-. Job XML Substitution is performed (see section 8.8).
+. Job XML Substitution is performed (see section xref:_job_xml_substitution[8.8]).
 . Start by setting the current position to the restart position. The restart position is either:
 .. the execution element identified by the <stop> elements "restart"
 attribute if that is how the previous execution ended; else
 .. the initial execution element determined the same as upon initial
-job start, as described in section 8.2.5 Step Sequence;
+job start, as described in section xref:_step_sequence[8.2.5] Step Sequence;
 . Determine if the current execution element should re-execute:
 .. If the current execution element is a COMPLETED step that specifies allow-restart-if-complete=false, then transition based on the exit status for this step from the previous completed execution. If the transition is a next transition, then repeat step 3 here with the value of next as the new, "current" execution element. Or, if the transition
 is a terminating transition such as end, stop, or fail, then terminate
@@ -254,11 +254,11 @@ exit status from the new step execution.+
 +
 Note if the step is a partitioned step, only the partitions that did not
 complete previously are restarted. This behavior may be overridden via a
-PartitionMapper (see section 10.8.5).  Note
+PartitionMapper (see section xref:_batchruntime[10.8.5]).  Note
 for a partitioned step, the checkpoints and persistent user data are
 loaded from the persistent store on a per-partition basis (this is not a
 new rule, but a fact implied by the discussion of checkpoints in section
-8.2.6 and the Step Context in section 9.4.1.1, which is summarized here
+xref:_step_partitioning[8.2.6] and the Step Context in section 9.4.1.1, which is summarized here
 for convenience).
 ..  If the current execution element is a decision, execute the decision
 (i.e. execute the Decider) unconditionally. The Deciders "decide" method
@@ -272,7 +272,7 @@ StepExecution(s) in the same array.
 execution element in the flow and perform step 3 with this as the
 current element. When restart processing of the flow has completed, then
 follow the same rules which apply during the original execution (see
-section 8.9) to transition at the flow level to the next execution
+section xref:_transitioning_rules[8.9]) to transition at the flow level to the next execution
 element, and repeat step 3 with that element as the current element. +
 +
 Note the same rules regarding transitioning within a flow during an
diff --git a/specification/src/main/asciidoc/domain_language.adoc b/specification/src/main/asciidoc/domain_language.adoc
index fa3d8b2..5712193 100644
--- a/specification/src/main/asciidoc/domain_language.adoc
+++ b/specification/src/main/asciidoc/domain_language.adoc
@@ -83,7 +83,7 @@ from where you left off'.
 Job parameters can be specified each time a job is started or restarted.
 Job parameters are keyword/value string pairs. The JobOperator start and
 restart operations support the specification of job parameters. See
-section 10.4 for further details on JobOperator.
+section xref:_joboperator_2[10.4] for further details on JobOperator.
 
 ==== JobExecution
 A JobExecution refers to the technical concept of a single attempt to
@@ -117,7 +117,7 @@ StepExecution will only be created when its Step is actually started.
 JobOperator provides an interface to manage all aspects of job
 processing, including operational commands, such as start, restart, and
 stop, as well as job repository related commands, such as retrieval of
-job and step executions. See section 10.4 for more details about
+job and step executions. See section xref:_joboperator_2[10.4] for more details about
 JobOperator.
 
 === Job Repository
diff --git a/specification/src/main/asciidoc/forward.adoc b/specification/src/main/asciidoc/forward.adoc
index 1ca9efe..c804ec9 100644
--- a/specification/src/main/asciidoc/forward.adoc
+++ b/specification/src/main/asciidoc/forward.adoc
@@ -1,2 +1,2 @@
-== Forward
+== Foreword
 This specification describes the job specification language, Java programming model, and runtime environment for batch applications for the Java platform. It is designed for use on both the Java SE and Java EE platforms. Additionally, it is designed to work with dependency injection (DI) containers without prescribing a particular DI implementation.
diff --git a/specification/src/main/asciidoc/job_specification_language.adoc b/specification/src/main/asciidoc/job_specification_language.adoc
index 3ce5539..6f796b8 100644
--- a/specification/src/main/asciidoc/job_specification_language.adoc
+++ b/specification/src/main/asciidoc/job_specification_language.adoc
@@ -58,7 +58,7 @@ The 'properties' element may be specified as a child element of the job
 element. It is used to expose properties to any batch artifact belonging
 to the job and also to the batch runtime. Any number of properties may
 be specified. Job level properties are available through the JobContext
-runtime object. See section 9.4 for further information about Job
+runtime object. See section xref:_batch_contexts[9.4] for further information about Job
 Context.
 
 Syntax:
@@ -82,7 +82,7 @@ be a valid XML string value. This is a required attribute.
 The 'step' element identifies a job step and its characteristics. Step
 is a child element of job. A job may contain any number of steps. Each
 step may be either a chunk type step or batchlet type step. See section
-8.2.1 for information on chunk type steps and section 8.2.2 for
+xref:_chunk[8.2.1] for information on chunk type steps and section xref:_batchlet[8.2.2] for
 information on batchlet type steps.
 
 Syntax:
@@ -125,7 +125,7 @@ of the step element. A chunk type step is periodically checkpointed by
 the batch runtime according to a configured checkpoint policy. Items
 processed between checkpoints are referred to as a "chunk". A single
 call is made to the ItemWriter per chunk. Each chunk is processed in a
-separate transaction. See section 9.7 for more details on
+separate transaction. See section xref:_transactionality[9.7] for more details on
 transactionality. A chunk that is not complete is restartable from its
 last checkpoint. A chunk that is complete and belongs to a step
 configured with allow-start-if-complete=true runs from the beginning
@@ -322,7 +322,7 @@ processor, writer batch artifacts of a chunk type step. It also applies
 to exceptions thrown during checkpoint commit processing. A failed
 commit will be treated the same as a failed write. The total number of
 skips is set by the skip-limit attribute on the chunk element. See
-section 8.2.1 for details on the chunk element.
+section xref:_chunk[8.2.1] for details on the chunk element.
 
 A given exception will be skipped if it "matches" an include child
 element of the skippable-exception-classes element, though this might be
@@ -348,7 +348,7 @@ exception.
 
 Optional Skip Listener batch artifacts can be configured to the step. A
 Skip Listener receives control after a skippable exception is thrown by
-the reader, processor, or writer. See section 9.2.7 for details on the
+the reader, processor, or writer. See section xref:_skip_listener_interfaces[9.2.7] for details on the
 Skip Listener batch interfaces.
 
 Syntax:
@@ -395,7 +395,7 @@ chunk element. It applies to exceptions thrown from the reader,
 processor, or writer batch artifacts of a chunk type step. It also
 applies to exceptions thrown by checkpoint commit processing. The total
 number of retry attempts is set by the retry-limit attribute on the
-chunk element. See section 8.2.1 for details on the chunk element.
+chunk element. See section xref:_chunk[8.2.1] for details on the chunk element.
 
 The list of exceptions that will be retried (or not retried) is
 specified in the retryable-exception-classes element on the child
@@ -407,7 +407,7 @@ in section 8.2.1.4.1 for skipping exceptions.
 
 Optional Retry Listener batch artifacts can be configured on the step. A
 Retry Listener receives control after a retryable exception is thrown by
-the reader, processor, or writer. See section 9.2.8 for details on the
+the reader, processor, or writer. See section xref:_retrylistener_interface[9.2.8] for details on the
 Retry Listener batch artifact.
 
 
@@ -476,7 +476,7 @@ This element is a child element of the chunk element. If a retryable
 exception is thrown the default behavior is to rollback before retry. If
 an exception is specified as both a retryable and a no-rollback
 exception, then no rollback occurs and the current operation is retried.
-Retry Listeners, if configured, are invoked. See section 9.2.8 for
+Retry Listeners, if configured, are invoked. See section xref:_retrylistener_interface[9.2.8] for
 details on the Retry Listener batch artifact.
 
 The rules for determining whether a combination of include and exclude
@@ -558,7 +558,7 @@ be a valid XML string value. This is a required attribute.
 
 The batchlet element specifies a task-oriented batch step. It is
 specified as a child element of the step element. It is mutually
-exclusive with the chunk element. See 9.1.2 for further details about
+exclusive with the chunk element. See xref:_batchlet_interface[9.1.2] for further details about
 batchlets. Steps of this type are useful for performing a variety of
 tasks that are not item-oriented, such as executing a command or doing
 file transfer.
@@ -576,7 +576,7 @@ Where:
 
 ===== Batchlet Exception Handling
 
-This section is superseded by section 8.2.7.
+This section is superseded by section xref:_step_exception_handling[8.2.7].
 
 ===== Batchlet Properties
 
@@ -609,7 +609,7 @@ The 'properties' element may be specified as a child element of the step
 element. It is used to expose properties to any step level batch
 artifact and also to the batch runtime. Any number of properties may be
 specified. Step level properties are available through the StepContext
-runtime object. See section 9.4 for further information about
+runtime object. See section xref:_batch_contexts[9.4] for further information about
 StepContext.
 
 Syntax:
@@ -725,8 +725,8 @@ inside a flow, the id must match another step in the same flow. This is
 a required attribute.
 |=======================================================================
 
-See section  8.6 for more details about transition
-elements and section 8.9 for details on transitioning rules.
+See section  xref:_transition_elements[8.6] for more details about transition
+elements and section xref:_transitioning_rules[8.9] for details on transitioning rules.
 
 ==== Step Partitioning
 
@@ -778,7 +778,7 @@ XML declaratively or dynamically at runtime with a partition mapper.
 
 The 'plan' element is a child element of the 'partition' element. The
 'plan' element is mutually exclusive with partition mapper element. See
-section 9.5.1 for further details on partition mapper.
+section xref:_partitionmapper_interface[9.5.1] for further details on partition mapper.
 
 Note the specification does not attempt to guarantee order of partition
 execution with respect to the order within a statically or
@@ -818,7 +818,7 @@ into 3 partitions on 2 threads:
 
 When defining a statically partitioned step, it is possible to specify
 unique property values to pass to each partition directly in the Job XML
-using the property element. See section 9.5.1 for further information on
+using the property element. See section xref:_partitionmapper_interface[9.5.1] for further information on
 partition mapper.
 
 Syntax:
@@ -867,7 +867,7 @@ The partition mapper provides a programmatic means for calculating the
 number of partitions and threads for a partitioned step. The partition
 mapper also specifies the properties for each partition. The mapper
 element specifies a reference to a PartitionMapper batch artifact; see
-section 9.5.1 for further information. Note the mapper element is
+section xref:_partitionmapper_interface[9.5.1] for further information. Note the mapper element is
 mutually exclusive with the plan element.
 
 Syntax:
@@ -917,7 +917,7 @@ partition reducer provides a kind of unit of work demarcation around the
 processing of the partitions. Programmatic interception of the
 partitioned step's lifecycle is possible through the partition reducer.
 The reducer element specifies a reference to a PartitionReducer batch
-artifact; see section 9.5.2 for further information.
+artifact; see section xref:_partitionreducer_interface[9.5.2] for further information.
 
 The 'reducer' element is a child element of the 'partition' element.
 
@@ -971,10 +971,10 @@ partition of the step. The collector is invoked at the conclusion of
 each checkpoint for chunking type steps and again at the end of
 partition; it is invoked once at the end of partition for batchlet type
 steps. A collector returns a Java Serializable object, which is
-delivered to the step's Partition Analyzer. See section 9.5.4 for
+delivered to the step's Partition Analyzer. See section xref:_partitionanalyzer_interface[9.5.4] for
 further information about the Partition Analyzer. The collector element
 specifies a reference to a PartitionCollector batch artifact; see
-section 9.5.3 for further information.
+section xref:_partitioncollector_interface[9.5.3] for further information.
 
 The 'collector' element is a child element of the 'partition' element.
 
@@ -1029,7 +1029,7 @@ PartitionAnalyzer also receives control with the partition exit status
 for each partition, after that partition ends. An analyzer can be used
 to implement custom exit status handling for the step, based on the
 results of the individual partitions. The analyzer element specifies a
-reference to a PartitionAnalyzer batch artifact; see section 9.5.4 for
+reference to a PartitionAnalyzer batch artifact; see section xref:_partitionanalyzer_interface[9.5.4] for
 further information.
 
 Syntax:
@@ -1083,7 +1083,7 @@ processing causes the step to terminate with a batch status of FAILED.
 In this context, "unhandled" means an exception thrown by the execution
 of the artifact back to the runtime implementation which does not result
 in a skip or a retry as described in section 8.2.1.4.
- See section 8.9.2 for complete details on
+ See section xref:_transitioning_precedence_rules[8.9.2] for complete details on
 transitioning after an unhandled exception.
 
 === Flow
@@ -1092,11 +1092,11 @@ A flow defines a sequence of execution elements that execute together as
 a unit. When the flow is finished, it is the entire flow that
 transitions to the next execution element. A flow may transition to a
 step, split, decision, or another flow. A flow may contain step, flow,
-decision, and split execution elements. See section 8.5 for more on
-decisions. See section 8.4 for more on splits. The execution elements
+decision, and split execution elements. See section xref:_decision[8.5] for more on
+decisions. See section xref:_split[8.4] for more on splits. The execution elements
 within a flow may only transition among themselves; they may not
 transition to elements outside of the flow. A flow may also contain the
-transition elements next, stop, fail, and end. See section 8.6 for more
+transition elements next, stop, fail, and end. See section xref:_transition_elements[8.6] for more
 on transition elements.
 
 Syntax:
@@ -1123,7 +1123,7 @@ a loop occurs among steps.
 === Split
 
 A split defines a set of flows that execute concurrently. A split may
-include only flow elements as children. See section 8.3 for more on
+include only flow elements as children. See section xref:_flow[8.3] for more on
 flows. Each flow runs on a separate thread. The split is finished after
 all flows complete. When the split is finished, it is the entire split
 that transitions to the next execution element. A split may transition
@@ -1157,7 +1157,7 @@ Incomplete
 The effort of the initial 1.0 final release specification to define
 split termination processing is recognized as incomplete. This is
 related to the recognition that flow transitioning is incomplete
-(section 8.9.5).
+(section xref:_flow_level_transitions[8.9.5]).
 
 As such, there is no well-defined mechanism for "passing back" status
 from the individual child flows of a split and aggregating them into a
@@ -1192,10 +1192,10 @@ steps, flows, and splits. The decision element may follow a step, flow,
 or split. A job may contain any number of decision elements. A decision
 element is the target of the "next" attribute from a job-level step,
 flow, split, or another decision. A decision must supply a decider batch
-artifact (see section 9.6). The decider's purpose is to decide the next
+artifact (see section xref:_decider_interface[9.6]). The decider's purpose is to decide the next
 transition. The decision uses any of the transition elements, stop,
 fail, end, and next elements to select the next transition. See section
-8.6 for further information on transition elements. The decider return
+xref:_transition_elements[8.6] for further information on transition elements. The decider return
 value will also be set as the current value of the job exit status, in
 addition to being matched against the decisions own child transition
 elements to decide the next transition.
@@ -1460,13 +1460,13 @@ A job execution will end under the following conditions:
 
 1.  A job-level execution element (step, flow, or split) finishes
 execution, without specifying a "next" attribute and without the exit
-status matching any transition elements. (See section 8.9.2 for
+status matching any transition elements. (See section xref:_transitioning_precedence_rules[8.9.2] for
 details).  In this case, the batch status is set
 to COMPLETED.
 2.  A step throws an exception to the batch runtime that does not match
 skip or retry criteria, with the exit status not matching any transition
 elements. In this case, the batch status is set to FAILED. (See section
-8.9.2 for details).  In the case of partitioned
+xref:_transitioning_precedence_rules[8.9.2] for details).  In the case of partitioned
 or concurrent (split) step execution, all other still-running parallel
 instances are allowed to complete before the job ends with FAILED batch
 status.
@@ -1483,7 +1483,7 @@ batch status to STARTED .
 status setter method on the JobContext object.
 3.  Exit status can be overridden by a decision element.
 4.  Exit status can be overridden by a terminating transition element on
-a step, flow, or split. See section 8.6.
+a step, flow, or split. See section xref:_transition_elements[8.6].
 5.  Final batch status is set by the batch runtime depending on the
 outcome of the job. See table above. Exit status is set to the final
 batch status if it was not overridden by any of the override means
@@ -1514,11 +1514,11 @@ the step, by the batch runtime. [line-through]*Step exit status is
 initially set to the same value as batch
 status.*  Step exit status may be set by any
 batch artifact configured to the step by invoking the exit status setter
-method in the StepContext object. See section 9.4 for further
+method in the StepContext object. See section xref:_batch_contexts[9.4] for further
 information about the StepContext object. Setting the step exit status
 does not alter the execution of the current step, but rather, is
 available to influence the execution of subsequent steps via transition
-elements (see 8.6) and deciders (see9.6). If no batch artifact sets the
+elements (see xref:_transition_elements[8.6]) and deciders (see xref:_decider_interface[9.6]). If no batch artifact sets the
 exit status, the batch runtime will default the value to the string form
 of the batch status value of the step when step execution completes.
 An important point to note is that transition elements do not affect the
@@ -1549,7 +1549,7 @@ this case).
 Note the implications for restart processing. For example, a completed
 step wont re-run just because the step includes a transition element
 failing the job on the original step executions exit status. See section
-10.8 for more on restart processing.
+xref:_supporting_classes[10.8] for more on restart processing.
 
 ==== Exit Status for Partitioned Steps
 
@@ -1618,7 +1618,7 @@ job can be started or restarted, except for the partitionPlan operator,
 which has deferred resolution - see section 8.8.1.4 for more on that.
 After substitution expression resolution, the resultant XML document
 must be checked for validity, according to the guidelines outlined in
-section 13, Job Specification Language XSD.
+section xref:_job_specification_language_2[13], Job Specification Language XSD.
 
 A substitution expression may reference a job parameter or a job
 property by specifying the name of the parameter or property through a
@@ -1924,7 +1924,7 @@ transitions to the element named by this next attribute value.
 3.  If execution ended normally, and the execution element whose
 execution is completing does not contain a next attribute, then the job
 ends normally (with COMPLETED batch status). For transitioning from a
-step within a flow, this statement doesnt apply. See section 8.9.4 for
+step within a flow, this statement doesnt apply. See section xref:_transitioning_from_within_flows[8.9.4] for
 details.
 
 The following examples illustrate how the above rules might be employed:
@@ -1956,7 +1956,7 @@ RecoveryStep.
 
 Note that the second example shows it is possible for a job to executed
 to COMPLETED status, even though a constituent step ends with FAILED
-batch status (See section 8.2.7).
+batch status (See section xref:_step_exception_handling[8.2.7]).
 
 ==== Loop definition
 
@@ -1974,11 +1974,11 @@ transitioned (back) to "step1". This may only be a single execution of
 prohibition.
 
 The runtime may detect potential loops in an initial validation phase,
-as described in section 13.1, or may only detect loops once they occur.
+as described in section xref:_validation_rules[13.1], or may only detect loops once they occur.
 
 ==== Transitioning From Within Flows
 
-As mentioned in section 8.3, an execution element which is a child of a
+As mentioned in section xref:_flow[8.3], an execution element which is a child of a
 flow may only transition to another execution element within the same
 flow. The flows transition elements, however, would transition execution
 to the next execution element at the level of the execution scope
@@ -1991,7 +1991,7 @@ failed or ended yet with another level of transitioning occurring at the
 containing (e.g. job) level.
 
 1.  Note: transition via next outside of the flow is not permitted. If
-this is not detected during job validation (see section 13.1), then at
+this is not detected during job validation (see section xref:_validation_rules[13.1]), then at
 runtime the job execution will end at this point with batch status of
 FAILED.
 
@@ -2000,19 +2000,19 @@ matching transition elements as well as no next attribute at the level
 of this child of a flow, then the flow ends.
 
 Another way of stating rules #2 and #3 in this section would be to say
-that all the rules in section 8.9.2 apply to transitions within flows
+that all the rules in section xref:_transitioning_precedence_rules[8.9.2] apply to transitions within flows
 (i.e. among children of flows) and are effective at the job level,
-except for rule #3 in section 8.9.2 (this case does not necessarily end
+except for rule #3 in section xref:_transitioning_precedence_rules[8.9.2] (this case does not necessarily end
 the job).
 
-See the example at the end of section 8.9.5 for further clarification.
+See the example at the end of section xref:_flow_level_transitions[8.9.5] for further clarification.
 
 ==== Flow-level Transitions
 Undefined
 
 It is recognized that the specification is incomplete with respect to
 how exactly flow transition elements are evaluated. Though the list in
-section 10.8.4 has an assertion in rule 3.e. that suggests using the
+section xref:_partitionplan[10.8.4] has an assertion in rule 3.e. that suggests using the
 exit status of the last contained execution element as a flow-level exit
 status, this does not seem to be a complete definition. For example,
 what if the last execution element within the flow is a split
@@ -2067,10 +2067,10 @@ As noted in the comments inline, this example makes the following
 points:
 
 * that a child of a flow can only transition to another child of
-the same flow (Item 1. in section 8.9.4)
+the same flow (Item 1. in section xref:_transitioning_from_within_flows[8.9.4])
 
 * that a terminating transition terminates the job, not just the
-flow somehow (Item 2. in section 8.9.4)
+flow somehow (Item 2. in section xref:_transitioning_from_within_flows[8.9.4])
 
 * that a transition element which is a direct child of the flow
-itself is currently UNDEFINED (section 8.9.5)
+itself is currently UNDEFINED (section xref:_flow_level_transitions[8.9.5])
diff --git a/specification/src/main/asciidoc/jsr352_1_0_a.adoc b/specification/src/main/asciidoc/jsr352_1_0_a.adoc
index 0dc594a..5a33db5 100644
--- a/specification/src/main/asciidoc/jsr352_1_0_a.adoc
+++ b/specification/src/main/asciidoc/jsr352_1_0_a.adoc
@@ -59,7 +59,7 @@ text of the spec delta or addition, but not in every single case.
 
 [width="100%",cols="<50%,<50%",]
 |=======================================================================
-|https://java.net/bugzilla/show_bug.cgiid=5389[5389] |In Sec. 10.7.1,
+|https://java.net/bugzilla/show_bug.cgiid=5389[5389] |In Sec. xref:_job_parameters_on_restart[10.7.1],
 should we have said we require a "no-arg" explicit or implicit
 constructor rather than a "default constructor"
 
@@ -97,7 +97,7 @@ transitioning & termination not fully defined
 |https://java.net/bugzilla/show_bug.cgiid=5374[5374] |Details of
 exception handling (by container)
 
-|https://java.net/bugzilla/show_bug.cgiid=4830[4830] |8.6.1 Transition
+|https://java.net/bugzilla/show_bug.cgiid=4830[4830] |xref:_next_element[8.6.1] Transition
 Next Element
 
 |https://java.net/bugzilla/show_bug.cgiid=4865[4865] |SPEC Partition