[groovy] branch master updated: overcome asciidoc multi-level link limitations (cont'd)

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

[groovy] branch master updated: overcome asciidoc multi-level link limitations (cont'd)

paulk
This is an automated email from the ASF dual-hosted git repository.

paulk pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/groovy.git


The following commit(s) were added to refs/heads/master by this push:
     new 0bd38dc  overcome asciidoc multi-level link limitations (cont'd)
0bd38dc is described below

commit 0bd38dca4e562101c1bfb17c65ee1d7a748594bc
Author: Paul King <[hidden email]>
AuthorDate: Tue Oct 13 22:50:01 2020 +1000

    overcome asciidoc multi-level link limitations (cont'd)
---
 src/spec/doc/core-differences-java.adoc            |  6 ++++-
 src/spec/doc/core-domain-specific-languages.adoc   | 17 +++++++++----
 src/spec/doc/core-getting-started.adoc             |  5 +++-
 src/spec/doc/core-metaprogramming.adoc             | 28 +++++++++++++++-------
 src/spec/doc/core-operators.adoc                   | 17 ++++++++-----
 src/spec/doc/core-program-structure.adoc           | 10 ++++++--
 src/spec/doc/core-semantics.adoc                   |  6 ++---
 src/spec/doc/core-syntax.adoc                      |  2 +-
 src/spec/doc/guide-integrating.adoc                |  5 +++-
 src/spec/doc/tools-groovyc.adoc                    |  5 +++-
 .../src/spec/doc/fragment_ant-builder.adoc         |  5 +++-
 .../groovy-ant/src/spec/doc/groovy-ant-task.adoc   |  7 ++++--
 .../groovy-ant/src/spec/doc/groovyc-ant-task.adoc  | 17 +++++++------
 subprojects/groovy-binary/src/spec/doc/index.adoc  | 19 +++++++++++----
 .../doc/fragment_working-with-datetime-types.adoc  |  5 +++-
 .../groovy-json/src/spec/doc/json-userguide.adoc   | 14 +++++++----
 .../src/spec/doc/fragment_swing-builder.adoc       |  5 +++-
 .../src/spec/doc/template-engines.adoc             |  5 +++-
 .../src/spec/doc/fragment_dom-builder.adoc         |  5 +++-
 .../groovy-xml/src/spec/doc/xml-userguide.adoc     |  1 +
 .../groovy-yaml/src/spec/doc/yaml-userguide.adoc   |  5 +++-
 21 files changed, 138 insertions(+), 51 deletions(-)

diff --git a/src/spec/doc/core-differences-java.adoc b/src/spec/doc/core-differences-java.adoc
index ad8d1e5..ab7d3a8 100644
--- a/src/spec/doc/core-differences-java.adoc
+++ b/src/spec/doc/core-differences-java.adoc
@@ -19,6 +19,10 @@
 
 //////////////////////////////////////////
 
+ifndef::core-semantics[]
+:core-semantics: core-semantics.adoc
+endif::[]
+
 = Differences with Java
 
 Groovy tries to be as natural as possible for Java developers. We’ve
@@ -344,7 +348,7 @@ Groovy expands greatly on this.
 explicitly cast, 'T` indicates a conversion Groovy can make but data is truncated, 'B' indicates a boxing/unboxing
 operation, 'N' indicates a conversion Groovy can't make.
 
-The truncation uses <<core-semantics.adoc#Groovy-Truth,Groovy Truth>> when converting to `boolean`/`Boolean`. Converting
+The truncation uses <<{core-semantics}#the-groovy-truth,Groovy Truth>> when converting to `boolean`/`Boolean`. Converting
 from a number to a character casts the `Number.intvalue()` to `char`. Groovy constructs `BigInteger` and `BigDecimal`
 using `Number.doubleValue()` when converting from a `Float` or `Double`, otherwise it constructs using `toString()`.
 Other conversions have their behavior defined by `java.lang.Number`.
diff --git a/src/spec/doc/core-domain-specific-languages.adoc b/src/spec/doc/core-domain-specific-languages.adoc
index 63ac377..556b993 100644
--- a/src/spec/doc/core-domain-specific-languages.adoc
+++ b/src/spec/doc/core-domain-specific-languages.adoc
@@ -21,6 +21,15 @@
 ifndef::reldir_root[]
 :reldir_root: .
 endif::[]
+ifndef::core-semantics[]
+:core-semantics: core-semantics.adoc
+endif::[]
+ifndef::xml-userguide[]
+:xml-userguide: xml-userguide.adoc
+endif::[]
+ifndef::jmx[]
+:jmx: jmx.adoc
+endif::[]
 
 = Domain-Specific Languages
 
@@ -1049,11 +1058,11 @@ link:type-checking-extensions.html[type checking extensions].
 
 ==== MarkupBuilder
 
-See <<xml-userguide.adoc#_markupbuilder,Creating Xml - MarkupBuilder>>.
+See <<{xml-userguide}#_markupbuilder,Creating Xml - MarkupBuilder>>.
 
 ==== StreamingMarkupBuilder
 
-See <<xml-userguide.adoc#_streamingmarkupbuilder,Creating Xml - StreamingMarkupBuilder>>.
+See <<{xml-userguide}#_streamingmarkupbuilder,Creating Xml - StreamingMarkupBuilder>>.
 
 include::../../../subprojects/groovy-xml/src/spec/doc/fragment_sax-builder.adoc[leveloffset=+3]
 
@@ -1071,7 +1080,7 @@ To create a simple user list you use a `NodeBuilder` like this:
 include::../test/builder/NodeBuilderTest.groovy[tags=node_builder_example,indent=0]
 ----
 
-Now you can process the data further, e.g. by using <<core-semantics.adoc#gpath_expressions,GPath expressions>>:
+Now you can process the data further, e.g. by using <<{core-semantics}#gpath_expressions,GPath expressions>>:
 
 [source,groovy]
 ----
@@ -1749,7 +1758,7 @@ referenced bean.
 
 ==== JmxBuilder
 
-See <<jmx.adoc#jmx_jmxbuilder,Working with JMX - JmxBuilder>> for details.
+See <<{jmx}#jmx_jmxbuilder,Working with JMX - JmxBuilder>> for details.
 
 ==== FileTreeBuilder
 
diff --git a/src/spec/doc/core-getting-started.adoc b/src/spec/doc/core-getting-started.adoc
index d6b9241..b5ca3d4 100644
--- a/src/spec/doc/core-getting-started.adoc
+++ b/src/spec/doc/core-getting-started.adoc
@@ -18,6 +18,9 @@
   under the License.
 
 //////////////////////////////////////////
+ifndef::groovy-console[]
+:groovy-console: groovy-console.adoc
+endif::[]
 
 = Getting started
 
@@ -177,7 +180,7 @@ You should now have Groovy installed properly. You can test this by typing the f
 groovysh
 ----
 
-Which should create an interactive groovy shell where you can type Groovy statements. Or to run the <<groovy-console.adoc#title-heading,Swing interactive console>> type:
+Which should create an interactive groovy shell where you can type Groovy statements. Or to run the <<{groovy-console}#title-heading,Swing interactive console>> type:
 
 [source,shell]
 ----
diff --git a/src/spec/doc/core-metaprogramming.adoc b/src/spec/doc/core-metaprogramming.adoc
index 20d4ee5..4ddbf25 100644
--- a/src/spec/doc/core-metaprogramming.adoc
+++ b/src/spec/doc/core-metaprogramming.adoc
@@ -18,6 +18,18 @@
   under the License.
 
 //////////////////////////////////////////
+ifndef::core-domain-specific-languages[]
+:core-domain-specific-languages: core-domain-specific-languages.adoc
+endif::[]
+ifndef::core-semantics[]
+:core-semantics: core-semantics.adoc
+endif::[]
+ifndef::core-testing-guide[]
+:core-testing-guide: core-testing-guide.adoc
+endif::[]
+ifndef::grape[]
+:grape: grape.adoc
+endif::[]
 
 = Metaprogramming
 
@@ -527,7 +539,7 @@ assert f2.class.toString() == "class Foo"
 Groovy comes with a special `MetaClass` the so-called `ExpandoMetaClass`. It is special in that it allows for dynamically
 adding or changing methods, constructors, properties and even static methods by using a neat closure syntax.
 
-Applying those modifications can be especially useful in mocking or stubbing scenarios as shown in the <<core-testing-guide.adoc#testing_guide_emc,Testing Guide>>.
+Applying those modifications can be especially useful in mocking or stubbing scenarios as shown in the <<{core-testing-guide}#testing_guide_emc,Testing Guide>>.
 
 Every `java.lang.Class` is supplied by Groovy with a special `metaClass` property that will give you a reference to an
 `ExpandoMetaClass` instance. This instance can then be used to add methods or change the behaviour of already existing
@@ -1787,7 +1799,7 @@ singleton, ...) by using a declarative style.
 
 `@BaseScript` is used within scripts to indicate that the script should
 extend fron a custom script base class rather than `groovy.lang.Script`.
-See the documentation for <<core-domain-specific-languages.adoc#dsl-basescript,domain specific languages>> for further details.
+See the documentation for <<{core-domain-specific-languages}#dsl-basescript,domain specific languages>> for further details.
 
 [[xform-Delegate]]
 ===== `@groovy.lang.Delegate`
@@ -2712,30 +2724,30 @@ Here, the `add` method will have final parameters but the `mult` method will rem
 [[xform-TypeChecked]]
 ===== `@groovy.transform.TypeChecked`
 
-`@TypeChecked` activates compile-time type checking on your Groovy code. See <<core-semantics#static-type-checking,section on type checking>> for details.
+`@TypeChecked` activates compile-time type checking on your Groovy code. See <<{core-semantics}#static-type-checking,section on type checking>> for details.
 
 [[xform-CompileStatic]]
 ===== `@groovy.transform.CompileStatic`
 
-`@CompileStatic` activates static compilation on your Groovy code. See <<core-semantics#static-type-checking,section on type checking>> for details.
+`@CompileStatic` activates static compilation on your Groovy code. See <<{core-semantics}#static-type-checking,section on type checking>> for details.
 
 [[xform-CompileDynamic]]
 ===== `@groovy.transform.CompileDynamic`
 
-`@CompileDynamic` disables static compilation on parts of your Groovy code. See <<core-semantics#static-type-checking,section on type checking>> for details.
+`@CompileDynamic` disables static compilation on parts of your Groovy code. See <<{core-semantics}#static-type-checking,section on type checking>> for details.
 
 [[xform-DelegatesTo]]
 ===== `@groovy.lang.DelegatesTo`
 
 `@DelegatesTo` is not, technically speaking, an AST transformation. It is aimed at documenting code and helping the compiler in case you are
 using <<xform-TypeChecked,type checking>> or <<xform-CompileStatic, static compilation>>. The annotation is described thoroughly in the
-<<core-domain-specific-languages.adoc#section-delegatesto,DSL section>> of this guide.
+<<{core-domain-specific-languages}#section-delegatesto,DSL section>> of this guide.
 
 [[xform-SelfType]]
 ===== `@groovy.transform.SelfType`
 
 `@SelfType` is not an AST transformation but rather a marker interface used
-with traits. See the <<core-object-orientation.adoc#traits-selftype,traits documentation>> for further details.
+with traits. See the <<{core-domain-specific-languages}#traits-selftype,traits documentation>> for further details.
 
 ==== Swing patterns
 
@@ -2931,7 +2943,7 @@ include::../test/TestingASTTransformsTest.groovy[tags=memorize_in_binding,indent
 ===== `@groovy.lang.Grapes`
 
 `Grape` is a dependency management engine embedded into Groovy, relying on several annotations which are described
-thoroughly in this <<grape#section-grape,section of the guide>>.
+thoroughly in this <<{grape}#section-grape,section of the guide>>.
 
 [[developing-ast-xforms]]
 === Developing AST transformations
diff --git a/src/spec/doc/core-operators.adoc b/src/spec/doc/core-operators.adoc
index 88b5e45..bf3fbba 100644
--- a/src/spec/doc/core-operators.adoc
+++ b/src/spec/doc/core-operators.adoc
@@ -18,11 +18,16 @@
   under the License.
 
 //////////////////////////////////////////
+ifndef::core-semantics[]
+:core-semantics: core-semantics.adoc
+endif::[]
+ifndef::core-syntax[]
+:core-syntax: core-syntax.adoc
+endif::[]
 
 [[groovy-operators]]
 = Operators
 
-
 This chapter covers the operators of the Groovy programming language.
 
 == Arithmetic operators
@@ -54,7 +59,7 @@ The following binary arithmetic operators are available in Groovy:
 
 | `/`
 | division
-| Use `intdiv()` for integer division, and see the section about <<core-syntax.adoc#integer_division,integer division>> for more information on the return type of the division.
+| Use `intdiv()` for integer division, and see the section about <<{core-syntax}#integer_division,integer division>> for more information on the return type of the division.
 
 | `%`
 | remainder
@@ -62,7 +67,7 @@ The following binary arithmetic operators are available in Groovy:
 
 | `**`
 | power
-| See the section about <<core-syntax.adoc#power_operator,the power operation>> for more information on the return type of the operation.
+| See the section about <<{core-syntax}#power_operator,the power operation>> for more information on the return type of the operation.
 |====
 
 Here are a few examples of usage of those operators:
@@ -295,7 +300,7 @@ In Groovy, bit shift operators are <<Operator-Overloading,overloadable>>, meanin
 === Not operator
 
 The "not" operator is represented with an exclamation mark (`!`) and inverts the result of the underlying boolean expression. In
-particular, it is possible to combine the `not` operator with the <<core-semantics.adoc#Groovy-Truth,Groovy truth>>:
+particular, it is possible to combine the `not` operator with the <<{core-semantics}#the-groovy-truth,Groovy truth>>:
 
 [source,groovy]
 ----
@@ -321,7 +326,7 @@ You can write:
 include::../test/OperatorsTest.groovy[tags=conditional_op_ternary_ternary,indent=0]
 ----
 
-The ternary operator is also compatible with the <<core-semantics.adoc#Groovy-Truth,Groovy truth>>, so you can make it even simpler:
+The ternary operator is also compatible with the <<{core-semantics}#the-groovy-truth,Groovy truth>>, so you can make it even simpler:
 
 [source,groovy]
 ----
@@ -332,7 +337,7 @@ include::../test/OperatorsTest.groovy[tags=conditional_op_ternary_groovytruth,in
 
 The "Elvis operator" is a shortening of the ternary operator. One instance of where this is handy is for returning
 a 'sensible default' value if an expression resolves to `false`-ish (as in
-<<core-semantics.adoc#Groovy-Truth,Groovy truth>>). A simple example might look like this:
+<<{core-semantics}#the-groovy-truth,Groovy truth>>). A simple example might look like this:
 
 [source,groovy]
 ----
diff --git a/src/spec/doc/core-program-structure.adoc b/src/spec/doc/core-program-structure.adoc
index f4dcbc2..8412f1d 100644
--- a/src/spec/doc/core-program-structure.adoc
+++ b/src/spec/doc/core-program-structure.adoc
@@ -18,6 +18,12 @@
   under the License.
 
 //////////////////////////////////////////
+ifndef::core-metaprogramming[]
+:core-metaprogramming: core-metaprogramming.adoc
+endif::[]
+ifndef::guide-integrating[]
+:guide-integrating: guide-integrating.adoc
+endif::[]
 
 = Program structure
 
@@ -261,10 +267,10 @@ a variable will *not* be visible in other methods of the script
 * if the variable is undeclared, it goes into the gapi:groovy.lang.Script#getBinding()[script binding]. The binding is
 visible from the methods, and is especially important if you use a script to interact with an application and need to
 share data between the script and the application. Readers might refer to the
-<<guide-integrating.adoc#_integrating_groovy_in_a_java_application,integration guide>> for more information.
+<<{guide-integrating}#_integrating_groovy_in_a_java_application,integration guide>> for more information.
 
 TIP: Another approach to making a variable visible to all methods, is to use the
-<<core-metaprogramming.adoc#xform-Field,@Field annotation>>.
+<<{core-metaprogramming}#xform-Field,@Field annotation>>.
 A variable annotated this way will become a field of the generated script class and,
 as for local variables, access won't involve the script `Binding`.
 While not recommended, if you have a local variable or script field with the same name as a binding variable,
diff --git a/src/spec/doc/core-semantics.adoc b/src/spec/doc/core-semantics.adoc
index ee0abde..7fc38b0 100644
--- a/src/spec/doc/core-semantics.adoc
+++ b/src/spec/doc/core-semantics.adoc
@@ -184,7 +184,7 @@ Switch supports the following kinds of comparisons:
 * Class case values match if the switch value is an instance of the class
 * Regular expression case values match if the `toString()` representation of the switch value matches the regex
 * Collection case values match if the switch value is contained in the collection. This also includes ranges (since they are Lists)
-* Closure case values match if the calling the closure returns a result which is true according to the <<Groovy-Truth,Groovy truth>>
+* Closure case values match if the calling the closure returns a result which is true according to the <<the-groovy-truth,Groovy truth>>
 * If none of the above are used then the case value matches if the case value equals the switch value
 
 NOTE: When using a closure case value, the default `it` parameter is actually the switch value (in our example, variable `x`).
@@ -475,7 +475,7 @@ As an example, you can specify a path to an object or element of interest:
 
 In both cases, the GPath expression can be viewed as a query on an object graph.  For POJOs, the object graph is most often built by the
 program being written through object instantiation and composition; for XML processing, the object graph is the result of `parsing`
-the XML text, most often with classes like XmlParser or XmlSlurper. See <<{xml-userguide}#Processing XML,Processing XML>>
+the XML text, most often with classes like XmlParser or XmlSlurper. See <<{xml-userguide}#processing-xml,Processing XML>>
 for more in-depth details on consuming XML in Groovy.
 
 [TIP]
@@ -894,7 +894,7 @@ is identical to this class:
 include::../test/semantics/OptionalityTest.groovy[tags=omitted_public,indent=0]
 ----
 
-[[Groovy-Truth]]
+[[the-groovy-truth]]
 == The Groovy Truth
 
 Groovy decides whether a expression is true or false by applying the rules given below.
diff --git a/src/spec/doc/core-syntax.adoc b/src/spec/doc/core-syntax.adoc
index af0a688..8315254 100644
--- a/src/spec/doc/core-syntax.adoc
+++ b/src/spec/doc/core-syntax.adoc
@@ -1011,7 +1011,7 @@ include::../test/SyntaxTest.groovy[tags=variable_store_boolean_value,indent=0]
 `true` and `false` are the only two primitive boolean values.
 But more complex boolean expressions can be represented using <<{core-operators}#_logical_operators,logical operators>>.
 
-In addition, Groovy has <<{core-semantics}#Groovy-Truth,special rules>> (often referred to as _Groovy Truth_)
+In addition, Groovy has <<{core-semantics}#the-groovy-truth,special rules>> (often referred to as _Groovy Truth_)
 for coercing non-boolean objects to a boolean value.
 
 == Lists
diff --git a/src/spec/doc/guide-integrating.adoc b/src/spec/doc/guide-integrating.adoc
index 8f1b5fe..86647c8 100644
--- a/src/spec/doc/guide-integrating.adoc
+++ b/src/spec/doc/guide-integrating.adoc
@@ -18,6 +18,9 @@
   under the License.
 
 //////////////////////////////////////////
+ifndef::core-domain-specific-languages[]
+:core-domain-specific-languages: core-domain-specific-languages.adoc
+endif::[]
 
 = Integrating Groovy in a Java application
 
@@ -162,7 +165,7 @@ include::../test/IntegrationTest.groovy[tags=custom_script_usage,indent=0]
 <4> the script now has access to the new method `greet`
 
 NOTE: You are not limited to the sole _scriptBaseClass_ configuration. You can use any of the compiler configuration
-tweaks, including the <<core-domain-specific-languages.adoc#compilation-customizers,compilation customizers>>.
+tweaks, including the <<{core-domain-specific-languages}#compilation-customizers,compilation customizers>>.
 
 [[groovyclassloader]]
 === GroovyClassLoader
diff --git a/src/spec/doc/tools-groovyc.adoc b/src/spec/doc/tools-groovyc.adoc
index 3d48d1d..9ef7f41 100644
--- a/src/spec/doc/tools-groovyc.adoc
+++ b/src/spec/doc/tools-groovyc.adoc
@@ -18,6 +18,9 @@
   under the License.
 
 //////////////////////////////////////////
+ifndef::groovyc-ant-task[]
+:groovyc-ant-task: groovyc-ant-task.adoc
+endif::[]
 
 = Compiling Groovy
 
@@ -60,7 +63,7 @@ a number of command line switches:
 
 == Ant task
 
-See the <<groovyc-ant-task.adoc#ThegroovycAntTask-groovyc,groovyc Ant task>> documentation.
+See the <<{groovyc-ant-task}#groovyc-ant-task-using,groovyc Ant task>> documentation.
 It allows the Groovy compiler to be invoked from http://ant.apache.org/[Apache Ant].
 
 [[Gant]]
diff --git a/subprojects/groovy-ant/src/spec/doc/fragment_ant-builder.adoc b/subprojects/groovy-ant/src/spec/doc/fragment_ant-builder.adoc
index ab19c67..e36d9f2 100644
--- a/subprojects/groovy-ant/src/spec/doc/fragment_ant-builder.adoc
+++ b/subprojects/groovy-ant/src/spec/doc/fragment_ant-builder.adoc
@@ -18,6 +18,9 @@
   under the License.
 
 //////////////////////////////////////////
+ifndef::groovy-ant-task[]
+:groovy-ant-task: groovy-ant-task.adoc
+endif::[]
 
 [[antbuilder]]
 = AntBuilder
@@ -25,7 +28,7 @@
 [NOTE]
 Here we describe `AntBuilder` which lets you write Ant build scripts
 in Groovy rather than XML. You may also be interested in using Groovy
-from Ant using the <<groovy-ant-task.adoc#ThegroovyAntTask-groovyc,Groovy Ant task>>.
+from Ant using the <<{groovy-ant-task}#groovy-ant-task-using,Groovy Ant task>>.
 
 Despite being primarily a build tool, https://ant.apache.org/[Apache Ant] is
 a very practical tool for manipulating files including zip files, copy, resource processing, and more.
diff --git a/subprojects/groovy-ant/src/spec/doc/groovy-ant-task.adoc b/subprojects/groovy-ant/src/spec/doc/groovy-ant-task.adoc
index 1252fb6..b12dff3 100644
--- a/subprojects/groovy-ant/src/spec/doc/groovy-ant-task.adoc
+++ b/subprojects/groovy-ant/src/spec/doc/groovy-ant-task.adoc
@@ -18,10 +18,13 @@
   under the License.
 
 //////////////////////////////////////////
+ifndef::core-domain-specific-languages[]
+:core-domain-specific-languages: core-domain-specific-languages.adoc
+endif::[]
 
 = The <groovy> Ant Task
 
-[[ThegroovyAntTask-groovyc]]
+[[groovy-ant-task-using]]
 == `<groovy>`
 
 [NOTE]
@@ -30,7 +33,7 @@ from within an Ant build file.
 You may also be interested in
 Ant's built-in https://ant.apache.org/manual/Tasks/script.html[`script`] task
 which supports Groovy and other languages, or
-<<ant-builder.adoc#antbuilder,`AntBuilder`>> which lets you write Ant build scripts
+<<{core-domain-specific-languages}#antbuilder,`AntBuilder`>> which lets you write Ant build scripts
 in Groovy rather than XML.
 
 Executes a series of Groovy statements from https://ant.apache.org/[Apache Ant].
diff --git a/subprojects/groovy-ant/src/spec/doc/groovyc-ant-task.adoc b/subprojects/groovy-ant/src/spec/doc/groovyc-ant-task.adoc
index 57da138..88a32f6 100644
--- a/subprojects/groovy-ant/src/spec/doc/groovyc-ant-task.adoc
+++ b/subprojects/groovy-ant/src/spec/doc/groovyc-ant-task.adoc
@@ -18,18 +18,21 @@
   under the License.
 
 //////////////////////////////////////////
+ifndef::tools-groovyc[]
+:tools-groovyc: tools-groovyc.adoc
+endif::[]
 
 = The <groovyc> Ant Task
 
-[[ThegroovycAntTask-groovyc]]
+[[groovyc-ant-task-using]]
 == `<groovyc>`
 
-[[ThegroovycAntTask-Description]]
+[[groovyc-ant-task-description]]
 === Description
 
 Compiles Groovy source files and, if joint compilation option is used, Java source files from http://ant.apache.org/[Apache Ant].
 
-[[ThegroovycAntTask-Requiredtaskdef]]
+[[groovyc-ant-task-taskdef]]
 === Required taskdef
 
 Assuming the groovy jars are in _groovy.libs_, you will need to declare this task
@@ -46,7 +49,7 @@ Consider also adding any additional Groovy module jars, libraries and potentiall
 </taskdef>
 -----------------------------------------------------------------------
 
-[[ThegroovycAntTask-groovycAttributes]]
+[[groovyc-ant-task-attributes]]
 === <groovyc> Attributes
 
 [cols="<,<,<",options="header,footer"]
@@ -159,7 +162,7 @@ the compilation fails. |No
 -----------------------------------------------------------------------
 
 
-[[ThegroovycAntTask-groovycNestedElements]]
+[[groovyc-ant-task-nested-elements]]
 === <groovyc> Nested Elements
 
 [cols="<,<,<,<",options="header,footer"]
@@ -184,7 +187,7 @@ you should not attempt to overwrite the destination. Other attributes and nested
 elements are unaffected, for example `fork`, `memoryMaximumSize`, etc. may be
 used freely.
 
-[[ThegroovycAntTask-JointCompilation]]
+[[groovyc-ant-task-joint-compilation]]
 === Joint Compilation
 
 Joint compilation is enabled by using an embedded `javac` element, as shown in the following example:
@@ -201,4 +204,4 @@ Joint compilation is enabled by using an embedded `javac` element, as shown in t
 </groovyc>
 -----------------------------------------------------------------------
 
-More details about joint compilation can be found in the <<tools-groovyc.adoc#section-jointcompilation,joint compilation>> section.
+More details about joint compilation can be found in the <<{tools-groovyc}#section-jointcompilation,joint compilation>> section.
diff --git a/subprojects/groovy-binary/src/spec/doc/index.adoc b/subprojects/groovy-binary/src/spec/doc/index.adoc
index 74c6743..cc7fd06 100644
--- a/subprojects/groovy-binary/src/spec/doc/index.adoc
+++ b/subprojects/groovy-binary/src/spec/doc/index.adoc
@@ -27,17 +27,28 @@ include::{reldir_root}/core-introduction.adoc[]
 
 == Groovy Language Specification
 
-:core-semantics:
+:core-domain-specific-languages:
+:core-metaprogramming:
+:core-object-orientation:
 :core-operators:
+:core-semantics:
+:core-syntax:
+:core-testing-guide:
+:grape:
+:groovy-ant-task:
+:groovy-console:
+:groovyc-ant-task:
+:guide-integrating:
+:jmx:
+:tools-groovyc:
+:xml-userguide:
+
 include::{reldir_root}/core-syntax.adoc[leveloffset=+2]
 
 include::{reldir_root}/core-operators.adoc[leveloffset=+2]
 
 include::{reldir_root}/core-program-structure.adoc[leveloffset=+2]
 
-:core-object-orientation:
-:core-syntax:
-:xml-userguide:
 include::{reldir_root}/core-object-orientation.adoc[leveloffset=+2]
 
 include::{reldir_root}/core-closures.adoc[leveloffset=+2]
diff --git a/subprojects/groovy-datetime/src/spec/doc/fragment_working-with-datetime-types.adoc b/subprojects/groovy-datetime/src/spec/doc/fragment_working-with-datetime-types.adoc
index 5b0db9f..05b2daa 100644
--- a/subprojects/groovy-datetime/src/spec/doc/fragment_working-with-datetime-types.adoc
+++ b/subprojects/groovy-datetime/src/spec/doc/fragment_working-with-datetime-types.adoc
@@ -18,6 +18,9 @@
   under the License.
 
 //////////////////////////////////////////
+ifndef::core-operators[]
+:core-operators: core-operators.adoc
+endif::[]
 
 = Working with Date/Time types
 
@@ -208,7 +211,7 @@ include::../test/gdk/WorkingWithDateTimeTypesTest.groovy[tags=property_notation,
 
 === Ranges, `upto`, and `downto`
 
-The JSR 310 types can be used with the <<core-operators.adoc#_range_operator,range operator>>.
+The JSR 310 types can be used with the <<{core-operators}#_range_operator,range operator>>.
 The following example iterates between today and the `LocalDate` six days from now,
 printing out the day of the week for each iteration. As both range bounds are inclusive,
 this prints all seven days of the week.
diff --git a/subprojects/groovy-json/src/spec/doc/json-userguide.adoc b/subprojects/groovy-json/src/spec/doc/json-userguide.adoc
index e6b6136..7c020ac 100644
--- a/subprojects/groovy-json/src/spec/doc/json-userguide.adoc
+++ b/subprojects/groovy-json/src/spec/doc/json-userguide.adoc
@@ -18,6 +18,12 @@
   under the License.
 
 //////////////////////////////////////////
+ifndef::core-semantics[]
+:core-semantics: core-semantics.adoc
+endif::[]
+ifndef::core-domain-specific-languages[]
+:core-domain-specific-languages: core-domain-specific-languages.adoc
+endif::[]
 
 = Processing JSON
 
@@ -64,7 +70,7 @@ is transparent. In fact, `JsonSlurper` results conform to GPath expressions. GPa
 that is supported by multiple slurpers for different data formats (`XmlSlurper` for XML being one example).
 
 [NOTE]
-For more details please have a look at the section on <<core-semantics.adoc#gpath_expressions,GPath expressions>>.
+For more details please have a look at the section on <<{core-semantics}#gpath_expressions,GPath expressions>>.
 
 The following table gives an overview of the JSON types and the corresponding Groovy data types:
 
@@ -156,7 +162,7 @@ include::../test/json/JsonTest.groovy[tags=set_type,indent=0]
 == JsonOutput
 
 `JsonOutput` is responsible for serialising Groovy objects into JSON strings. It can be seen as companion object to
-<<json-userguide.adoc#json_jsonslurper,JsonSlurper>>, being a JSON parser.
+<<#json_jsonslurper,JsonSlurper>>, being a JSON parser.
 
 `JsonOutput` comes with overloaded, static `toJson` methods. Each `toJson` implementation takes a different parameter type.
 The static methods can either be used directly or by importing the methods with a static import statement.
@@ -217,5 +223,5 @@ Another way to create JSON from Groovy is to use `JsonBuilder` or `StreamingJson
 DSL which allows to formulate an object graph which is then converted to JSON.
 
 [NOTE]
-For more details on builders, have a look at the builders chapter which covers both <<core-domain-specific-languages.adoc#_jsonbuilder,JsonBuilder>>
-and <<core-domain-specific-languages.adoc#_streamingjsonbuilder,StreamingJsonBuilder>>.
+For more details on builders, have a look at the builders chapter which covers both <<{core-domain-specific-languages}#_jsonbuilder,JsonBuilder>>
+and <<{core-domain-specific-languages}#_streamingjsonbuilder,StreamingJsonBuilder>>.
diff --git a/subprojects/groovy-swing/src/spec/doc/fragment_swing-builder.adoc b/subprojects/groovy-swing/src/spec/doc/fragment_swing-builder.adoc
index 4181671..e202d14 100644
--- a/subprojects/groovy-swing/src/spec/doc/fragment_swing-builder.adoc
+++ b/subprojects/groovy-swing/src/spec/doc/fragment_swing-builder.adoc
@@ -21,6 +21,9 @@
 ifndef::reldir_swing[]
 :reldir_swing: .
 endif::[]
+ifndef::core-metaprogramming[]
+:core-metaprogramming: core-metaprogramming.adoc
+endif::[]
 
 [[swingbuilder]]
 = SwingBuilder
@@ -60,4 +63,4 @@ Here's another variation that relies on observable beans and binding:
 include::../test/SwingBuilderTest.groovy[tags=observable_binding_example,indent=0]
 ----
 
-<<core-metaprogramming.adoc#xform-Bindable,@Bindable>> is one of the core AST Transformations. It generates all the required boilerplate code to turn a simple bean into an observable one. The `bind()` node creates appropriate `PropertyChangeListeners` that will update the interested parties whenever a `PropertyChangeEvent` is fired.
\ No newline at end of file
+<<{core-metaprogramming}#xform-Bindable,@Bindable>> is one of the core AST Transformations. It generates all the required boilerplate code to turn a simple bean into an observable one. The `bind()` node creates appropriate `PropertyChangeListeners` that will update the interested parties whenever a `PropertyChangeEvent` is fired.
\ No newline at end of file
diff --git a/subprojects/groovy-templates/src/spec/doc/template-engines.adoc b/subprojects/groovy-templates/src/spec/doc/template-engines.adoc
index 6107e87..c2cd114 100644
--- a/subprojects/groovy-templates/src/spec/doc/template-engines.adoc
+++ b/subprojects/groovy-templates/src/spec/doc/template-engines.adoc
@@ -18,12 +18,15 @@
   under the License.
 
 //////////////////////////////////////////
+ifndef::xml-userguide[]
+:xml-userguide: xml-userguide.adoc
+endif::[]
 
 = Template engines
 
 == Introduction
 
-Groovy supports multiple ways to generate text dynamically including `GStrings`, `printf` and <<xml-userguide.adoc#_markupbuilder, MarkupBuilder>> just to name a few.
+Groovy supports multiple ways to generate text dynamically including `GStrings`, `printf` and <<{xml-userguide}#_markupbuilder, MarkupBuilder>> just to name a few.
 In addition to these, there is a dedicated template framework which is well-suited to applications where the text to be generated follows the form of a static template.
 
 == Template framework
diff --git a/subprojects/groovy-xml/src/spec/doc/fragment_dom-builder.adoc b/subprojects/groovy-xml/src/spec/doc/fragment_dom-builder.adoc
index d672a68..2b50eec 100644
--- a/subprojects/groovy-xml/src/spec/doc/fragment_dom-builder.adoc
+++ b/subprojects/groovy-xml/src/spec/doc/fragment_dom-builder.adoc
@@ -18,6 +18,9 @@
   under the License.
 
 //////////////////////////////////////////
+ifndef::xml-userguide[]
+:xml-userguide: xml-userguide.adoc
+endif::[]
 
 = DOMBuilder
 
@@ -37,7 +40,7 @@ Can be parsed into a DOM tree with a `DOMBuilder` like this:
 include::../test/DOMBuilderTest.groovy[tags=dom_builder_parse,indent=0]
 ----
 
-And then processed further e.g. by using <<xml-userguide.adoc#_domcategory,DOMCategory>>:
+And then processed further e.g. by using <<{xml-userguide}#_domcategory,DOMCategory>>:
 
 [source,groovy]
 ----
diff --git a/subprojects/groovy-xml/src/spec/doc/xml-userguide.adoc b/subprojects/groovy-xml/src/spec/doc/xml-userguide.adoc
index 0e29cd2..a438eb1 100644
--- a/subprojects/groovy-xml/src/spec/doc/xml-userguide.adoc
+++ b/subprojects/groovy-xml/src/spec/doc/xml-userguide.adoc
@@ -19,6 +19,7 @@
 
 //////////////////////////////////////////
 
+[[processing-xml]]
 = Processing XML
 
 == Parsing XML
diff --git a/subprojects/groovy-yaml/src/spec/doc/yaml-userguide.adoc b/subprojects/groovy-yaml/src/spec/doc/yaml-userguide.adoc
index 571932a..1d40327 100644
--- a/subprojects/groovy-yaml/src/spec/doc/yaml-userguide.adoc
+++ b/subprojects/groovy-yaml/src/spec/doc/yaml-userguide.adoc
@@ -18,6 +18,9 @@
   under the License.
 
 //////////////////////////////////////////
+ifndef::core-semantics[]
+:core-semantics: core-semantics.adoc
+endif::[]
 
 = Processing YAML
 
@@ -49,7 +52,7 @@ is transparent. In fact, `YamlSlurper` results conform to GPath expressions. GPa
 that is supported by multiple slurpers for different data formats (`XmlSlurper` for XML being one example).
 
 [NOTE]
-For more details please have a look at the section on <<core-semantics.adoc#gpath_expressions,GPath expressions>>.
+For more details please have a look at the section on <<{core-semantics}#gpath_expressions,GPath expressions>>.
 
 The following table gives an overview of the YAML types and the corresponding Groovy data types: