Fix cross references

Issue gh-869

Author: rwinch

modules/ROOT/pages/configuration.adoc

@@ -66,7 +66,7 @@ The configurable attributes on context-source are as follows (required attribute
 | `LdapUtils.emptyLdapName()`
 |  The base DN. When this attribute has been configured, all Distinguished Names supplied to and received from LDAP operations are relative to the specified LDAP path.
    This can significantly simplify working against the LDAP tree. However, there are several occasions when you need to have access to the base path.
-   For more information on this, see <<base-context-configuration>>
+   For more information on this, see xref:configuration.adoc#base-context-configuration[Obtaining a Reference to the Base LDAP Path]
 
 | `anonymous-read-only`
 | `false`
@@ -83,15 +83,15 @@ a|  Defines the strategy with which to handle referrals, as described https://do
 
 | `native-pooling`
 | `false`
-|  Specify whether native Java LDAP connection pooling should be used. Consider using Spring LDAP connection pooling instead. See <<pooling>> for more information.
+|  Specify whether native Java LDAP connection pooling should be used. Consider using Spring LDAP connection pooling instead. See xref:pooling.adoc[Pooling Support] for more information.
 
 | `authentication-source-ref`
 |  A `SimpleAuthenticationSource` instance.
-|  ID of the `AuthenticationSource` instance to use (see <<spring-ldap-custom-principal-credentials-management>>).
+|  ID of the `AuthenticationSource` instance to use (see xref:configuration.adoc#spring-ldap-custom-principal-credentials-management[Custom Principal and Credentials Management]).
 
 | `authentication-strategy-ref`
 |  A `SimpleDirContextAuthenticationStrategy` instance.
-|  ID of the `DirContextAuthenticationStrategy` instance to use (see <<spring-ldap-custom-dircontext-authentication-processing>>).
+|  ID of the `DirContextAuthenticationStrategy` instance to use (see xref:configuration.adoc#spring-ldap-custom-dircontext-authentication-processing[Custom `DirContext` Authentication Processing]).
 
 | `base-env-props-ref`
 |
@@ -104,7 +104,7 @@ a|  Defines the strategy with which to handle referrals, as described https://do
 When `DirContext` instances are created to be used for performing operations on an LDAP server, these contexts often need to be authenticated.
 Spring LDAP offers various options for configuring this.
 
-NOTE: This section refers to authenticating contexts in the core functionality of the `ContextSource`, to construct `DirContext` instances for use by `LdapClient` and `LdapTemplate`. LDAP is commonly used for the sole purpose of user authentication, and the `ContextSource` may be used for that as well. That process is discussed in <<user-authentication>>.
+NOTE: This section refers to authenticating contexts in the core functionality of the `ContextSource`, to construct `DirContext` instances for use by `LdapClient` and `LdapTemplate`. LDAP is commonly used for the sole purpose of user authentication, and the `ContextSource` may be used for that as well. That process is discussed in xref:user-authentication.adoc[User Authentication using Spring LDAP].
 
 By default, authenticated contexts are created for both read-only and read-write operations. You should specify the `username` and `password` of the LDAP user to be used for authentication on the `context-source` element.
 
@@ -130,7 +130,7 @@ Where `DefaultTlsDirContextAuthenticationStrategy` applies SIMPLE authentication
 
 Since different LDAP server implementations respond differently to explicit shutdown of the TLS channel (some servers require the connection be shut down gracefully, while others do not support it), the TLS `DirContextAuthenticationStrategy` implementations support specifying the shutdown behavior by using the `shutdownTlsGracefully` parameter. If this property is set to `false` (the default), no explicit TLS shutdown happens. If it is `true`, Spring LDAP tries to shut down the TLS channel gracefully before closing the target context.
 
-NOTE: When working with TLS connections, you need to make sure that the native LDAP Pooling functionality (as specified by using the `native-pooling` attribute) is turned off. This is particularly important if `shutdownTlsGracefully` is set to `false`. However, since the TLS channel negotiation process is quite expensive, you can gain great performance benefits by using the Spring LDAP Pooling Support, described in <<pooling>>.
+NOTE: When working with TLS connections, you need to make sure that the native LDAP Pooling functionality (as specified by using the `native-pooling` attribute) is turned off. This is particularly important if `shutdownTlsGracefully` is set to `false`. However, since the TLS channel negotiation process is quite expensive, you can gain great performance benefits by using the Spring LDAP Pooling Support, described in xref:pooling.adoc[Pooling Support].
 
 [[spring-ldap-custom-principal-credentials-management]]
 ==== Custom Principal and Credentials Management
@@ -167,7 +167,7 @@ NOTE: When using the `SpringSecurityAuthenticationSource`, you need to use Sprin
 
 The internal Java LDAP provider provides some very basic pooling capabilities. You can turn this LDAP connection pooling on or off by using the `pooled` flag on `AbstractContextSource`.  The default value is `false` (since release 1.3) -- that is, the native Java LDAP pooling is turned off. The configuration of LDAP connection pooling is managed by using `System` properties, so you need to handle this manually, outside of the Spring Context configuration. You can find details of the native pooling configuration https://java.sun.com/products/jndi/tutorial/ldap/connect/config.html[here].
 
-NOTE: There are several serious deficiencies in the built-in LDAP connection pooling, which is why Spring LDAP provides a more sophisticated approach to LDAP connection pooling, described in <<pooling>>. If you need pooling functionality, this is the recommended approach.
+NOTE: There are several serious deficiencies in the built-in LDAP connection pooling, which is why Spring LDAP provides a more sophisticated approach to LDAP connection pooling, described in xref:pooling.adoc[Pooling Support]. If you need pooling functionality, this is the recommended approach.
 
 NOTE: Regardless of the pooling configuration, the `ContextSource#getContext(String principal, String credentials)` method always explicitly does not use native Java LDAP Pooling, in order for reset passwords to take effect as soon as possible.
 

modules/ROOT/pages/dirobjectfactory.adoc

@@ -105,7 +105,7 @@ involved in adding and updating data.
 [[adding-data-by-using-dircontextadapter]]
 === Adding Data by Using `DirContextAdapter`
 
-The following example uses `DirContextAdapter` to implement an improved implementation of the `create` repository method presented in <<basic-binding-data>>:
+The following example uses `DirContextAdapter` to implement an improved implementation of the `create` repository method presented in xref:spring-ldap-basic-usage.adoc#basic-binding-data[Adding Data]:
 
 .Binding using `DirContextAdapter`
 ====
@@ -286,7 +286,7 @@ public class GroupRepo implements BaseLdapNameAware {
 ----
 ====
 
-In the preceding example, we implement `BaseLdapNameAware` to get the base LDAP path as described in <<base-context-configuration>>.
+In the preceding example, we implement `BaseLdapNameAware` to get the base LDAP path as described in xref:configuration.adoc#base-context-configuration[Obtaining a Reference to the Base LDAP Path].
 This is necessary because distinguished names as member attribute values must always be absolute from the directory root.
 
 [[a-complete-personrepository-class]]
@@ -397,5 +397,5 @@ public class PersonRepoImpl implements PersonRepo {
 NOTE: In several cases, the Distinguished Name (DN) of an object is constructed by using properties of the object.
 In the preceding example, the country, company and full name of the `Person` are used in the DN, which means that updating any of these properties actually requires moving the entry in the LDAP tree by using the `rename()` operation in addition to updating the `Attribute` values.
 Since this is highly implementation-specific, this is something you need to keep track of yourself, either by disallowing the user to change these properties or performing the `rename()` operation in your `update()` method if needed.
-Note that, by using <<odm>>, the library can automatically handle this for you if you annotate your domain classes appropriately.
+Note that, by using xref:odm.adoc[Object-Directory Mapping (ODM)], the library can automatically handle this for you if you annotate your domain classes appropriately.
 

modules/ROOT/pages/introduction.adoc

@@ -3,15 +3,15 @@
 
 This section offers a relatively quick introduction to Spring LDAP. It includes the following content:
 
-* <<spring-ldap-introduction-overview>>
-* <<spring-ldap-traditional-ldap-vs-ldaptemplate>>
-* <<spring-ldap-new-2.2>>
-* <<spring-ldap-new-2.1>>
-* <<spring-ldap-new-2.0>>
-* <<spring-ldap-packaging-overview>>
-* <<spring-ldap-getting-started>>
-* <<spring-ldap-support>>
-* <<spring-ldap-acknowledgements>>
+* xref:introduction.adoc#spring-ldap-introduction-overview[Overview]
+* xref:introduction.adoc#spring-ldap-traditional-ldap-vs-ldaptemplate[Traditional Java LDAP versus `LdapClient`]
+* xref:introduction.adoc#spring-ldap-new-2.2[What's new in 2.2]
+* xref:introduction.adoc#spring-ldap-new-2.1[What's new in 2.1]
+* xref:introduction.adoc#spring-ldap-new-2.0[What's new in 2.0]
+* xref:introduction.adoc#spring-ldap-packaging-overview[Packaging Overview]
+* xref:introduction.adoc#spring-ldap-getting-started[Getting Started]
+* xref:introduction.adoc#spring-ldap-support[Support]
+* xref:introduction.adoc#spring-ldap-acknowledgements[Acknowledgements]
 
 [[spring-ldap-introduction-overview]]
 == Overview
@@ -201,15 +201,15 @@ The following list briefly describes the most important changes in Spring LDAP 2
 *  The central API has been updated with Java 5+ features such as generics and varargs.
    As a consequence, the entire `spring-ldap-tiger` module has been deprecated, and we encourage you to migrate to using the core Spring LDAP classes.
    The parameterization of the core interfaces causes lots of compilation warnings on existing code, and we encourage you to take appropriate action to get rid of these warnings.
-*  The ODM (Object-Directory Mapping) functionality has been moved to core, and there are new methods in `LdapOperations` and `LdapTemplate` that use this automatic translation to and from ODM-annotated classes. See <<odm>> for more information.
+*  The ODM (Object-Directory Mapping) functionality has been moved to core, and there are new methods in `LdapOperations` and `LdapTemplate` that use this automatic translation to and from ODM-annotated classes. See xref:odm.adoc[Object-Directory Mapping (ODM)] for more information.
 *  A custom XML namespace is now (finally) provided to simplify configuration of Spring LDAP. See <<configuration>> for more information.
-*  Spring LDAP now provides support for Spring Data Repository and QueryDSL. See <<repositories>> for more information.
+*  Spring LDAP now provides support for Spring Data Repository and QueryDSL. See xref:repositories.adoc[Spring LDAP Repositories] for more information.
 *  `Name` instances as attribute values are now handled properly with regards to distinguished name equality in `DirContextAdapter` and ODM.
-   See <<dns-as-attribute-values>> and <<odm-dn-attributes>> for more information.
+   See xref:dirobjectfactory.adoc#dns-as-attribute-values[`DirContextAdapter` and Distinguished Names as Attribute Values] and xref:odm.adoc#odm-dn-attributes[ODM and Distinguished Names as Attribute Values] for more information.
 *  `DistinguishedName` and associated classes have been deprecated in favor of the standard Java `LdapName`.
-   See <<ldap-names>> for information on how the library helps when working with `LdapName` objects.
+   See xref:spring-ldap-basic-usage.adoc#ldap-names[Dynamically Building Distinguished Names] for information on how the library helps when working with `LdapName` objects.
 *  Fluent LDAP query building support has been added. This makes for a more pleasant programming experience when working with LDAP searches in Spring LDAP.
-   See <<basic-queries>> and <<query-builder-advanced>> for more information about the LDAP query builder support.
+   See xref:spring-ldap-basic-usage.adoc#basic-queries[Building LDAP Queries] and xref:query-builder-advanced.adoc[Advanced LDAP Queries] for more information about the LDAP query builder support.
 *  The old `authenticate` methods in `LdapTemplate` have been deprecated in favor of a couple of new `authenticate` methods that work with `LdapQuery` objects and _throw exceptions_ on authentication failure, making it easier for the user to find out what caused an authentication attempt to fail.
 *  The https://github.com/spring-projects/spring-ldap/tree/main/samples[samples] have been polished and updated to make use of the features in 2.0.
    Quite a bit of effort has been put into providing a useful example of an https://github.com/spring-projects/spring-ldap/tree/main/samples/user-admin[LDAP user management application].

modules/ROOT/pages/odm.adoc

@@ -132,7 +132,7 @@ public class OdmPersonRepo {
 == ODM and Distinguished Names as Attribute Values
 
 Security groups in LDAP commonly contain a multi-value attribute, where each of the values is the distinguished name
-of a user in the system. The difficulties involved when handling these kinds of attributes are discussed in <<dns-as-attribute-values>>.
+of a user in the system. The difficulties involved when handling these kinds of attributes are discussed in xref:dirobjectfactory.adoc#dns-as-attribute-values[`DirContextAdapter` and Distinguished Names as Attribute Values].
 
 ODM also has support for `javax.naming.Name` attribute values, making group modifications easy, as the following example shows:
 

modules/ROOT/pages/pooling.adoc

@@ -13,7 +13,7 @@ Validation of pooled connections is the primary motivation for using a custom po
 If connection validation is configured, pooled connections are validated by using `DefaultDirContextValidator`.
 `DefaultDirContextValidator` does a `DirContext.search(String, String, SearchControls)`, with an empty name, a filter of `"objectclass=*"`, and `SearchControls` set to limit a single result with the only the `objectclass` attribute and a 500ms timeout. If the returned `NamingEnumeration` has results, the `DirContext` passes validation. If no results are returned or an exception is thrown, the `DirContext` fails validation.
 The default settings should work with no configuration changes on most LDAP servers and provide the fastest way to validate the `DirContext`.
-If you need customization, you can do so by using the validation configuration attributes, described in <<pool-configuration>>.
+If you need customization, you can do so by using the validation configuration attributes, described in xref:pooling.adoc#pool-configuration[Pool Configuration].
 
 NOTE: Connections are automatically invalidated if they throw an exception that is considered non-transient. For example, if a `DirContext` instance throws a `javax.naming.CommunicationException`, it is interpreted as a non-transient error and the instance is automatically invalidated, without the overhead of an additional `testOnReturn` operation. The exceptions that are interpreted as non-transient are configured by using the `nonTransientExceptions` property of the `PoolingContextSource`.
 
@@ -252,7 +252,7 @@ The following example tests each `DirContext` before it is passed to the client
 
 This section describes issues that sometimes arise when people use Spring LDAP. At present, it covers the following issues:
 
-* <<spring-ldap-known-issues-custom-authentication>>
+* xref:pooling.adoc#spring-ldap-known-issues-custom-authentication[Custom Authentication]
 
 [[spring-ldap-known-issues-custom-authentication]]
 === Custom Authentication

modules/ROOT/pages/repositories.adoc

@@ -7,7 +7,7 @@ Spring LDAP has built-in support for Spring Data repositories. The basic functio
 
 *  To include support for `LdapQuery` parameters in automatically generated repositories, have your interface extend `LdapRepository` rather than `CrudRepository`.
 
-*  All Spring LDAP repositories must work with entities that are annotated with the ODM annotations, as described in <<odm>>.
+*  All Spring LDAP repositories must work with entities that are annotated with the ODM annotations, as described in xref:odm.adoc[Object-Directory Mapping (ODM)].
 
 *  Since all ODM managed classes must have a Distinguished Name as the ID, all Spring LDAP repositories must have the ID type parameter set to `javax.naming.Name`.
    The built-in `LdapRepository` takes only one type parameter: the managed entity class, defaulting the ID to `javax.naming.Name`.
@@ -18,7 +18,7 @@ Spring LDAP has built-in support for Spring Data repositories. The basic functio
 == QueryDSL support
 Basic QueryDSL support is included in Spring LDAP. This support includes the following:
 
-*  An annotation processor, called `LdapAnnotationProcessor`, for generating QueryDSL classes based on Spring LDAP ODM annotations. See <<odm>> for more information on the ODM annotations.
+*  An annotation processor, called `LdapAnnotationProcessor`, for generating QueryDSL classes based on Spring LDAP ODM annotations. See xref:odm.adoc[Object-Directory Mapping (ODM)] for more information on the ODM annotations.
 
 *  A Query implementation, called `QueryDslLdapQuery`, for building and running QueryDSL queries in code.