Merge pull request #31548 from MichalMaler/QUARKUS-175-Fixing-old-anchors

Changed old documentation anchors markup for the XREF macro for proper synergy with the downstream documentation

Author: ebullient

docs/src/main/asciidoc/amazon-lambda.adoc

@@ -54,18 +54,18 @@ mvn archetype:generate \
 If you prefer to use Gradle, you can quickly and easily generate a Gradle project via https://code.quarkus.io/[code.quarkus.io]
 adding the `quarkus-amazon-lambda` extension as a dependency.
 
-Copy the build.gradle, gradle.properties and settings.gradle into the above generated Maven archetype project, to follow along with this guide.
+Copy the build.gradle, gradle.properties and settings.gradle into the above-generated Maven archetype project, to follow along with this guide.
 
 Execute: gradle wrapper to set up the gradle wrapper (recommended).
 
-For full Gradle details <<gradle, see below>>.
+For full Gradle details, see the xref:gradle[Gradle build] section below.
 ====
 
 [[choose]]
 == Choose Your Lambda
 
 The `quarkus-amazon-lambda` extension scans your project for a class that directly implements the Amazon `RequestHandler<?, ?>` or `RequestStreamHandler` interface.
-It must find a class in your project that implements this interface or it will throw a build time failure.
+It must find a class in your project that implements this interface, or it will throw a build time failure.
 If it finds more than one handler class, a build time exception will also be thrown.
 
 Sometimes, though, you might have a few related lambdas that share code and creating multiple maven modules is just
@@ -273,7 +273,7 @@ call must set a specific environment variable:
 There is nothing special about the POM other than the inclusion of the `quarkus-amazon-lambda` extension
 as a dependency.  The extension automatically generates everything you might need for your lambda deployment.
 
-NOTE: In previous versions of this extension you had to set up your pom or gradle
+NOTE: In previous versions of this extension, you had to set up your pom or gradle
 to zip up your executable for native deployments, but this is not the case anymore.
 
 [[gradle]]
@@ -452,13 +452,13 @@ Please check link:{amazon-services-guide}[those guides] on how to use the variou
 With minimal integration, it is possible to leverage the AWS Java SDK v2,
 which can be used to invoke services such as SQS, SNS, S3 and DynamoDB.
 
-For native image, however the URL Connection client must be preferred over the Apache HTTP Client
+For native image, however, the URL Connection client must be preferred over the Apache HTTP Client
 when using synchronous mode, due to issues in the GraalVM compilation (at present).
 
 Add `quarkus-jaxb` as a dependency in your Maven `pom.xml`, or Gradle `build.gradle` file.
 
 You must also force your AWS service client for SQS, SNS, S3 et al., to use the URL Connection client,
-which connects to AWS services over HTTPS, hence the inclusion of the SSL enabled property, as described in the <<https>> section above.
+which connects to AWS services over HTTPS, hence the inclusion of the SSL enabled property, as described in the xref:https[] section above.
 
 [source,java]
 ----

docs/src/main/asciidoc/cli-tooling.adoc

@@ -428,7 +428,7 @@ The behavior of `quarkus ext ls` will vary depending on context.
 
 If you invoke the Quarkus CLI from outside of a project, Quarkus will list all the extensions available for the Quarkus release used by the CLI itself.
 
-You can also list extensions for a specific release of Quarkus using `-P` or `-S`, as described in <<specifying-quarkus-version,Specifying the Quarkus version>>.
+You can also list extensions for a specific release of Quarkus using `-P` or `-S`, as described in xref:specifying-quarkus-version[Specifying the Quarkus version].
 
 This mode uses the `--origins` format by default.
 

docs/src/main/asciidoc/config.adoc

@@ -9,7 +9,7 @@ include::_attributes.adoc[]
 :summary: Hardcoded values in your code is a no go (even if we all did it at some point ;-)). In this guide, we learn how to configure your application.
 
 IMPORTANT: The content of this guide and been revised and split into additional topics. Please check the
-<<additional-information,Additional Information>> section.
+xref:additional-information[Additional Information] section.
 
 
 Hardcoded values in your code are a _no-go_ (even if we all did it at some point ;-)).
@@ -48,8 +48,9 @@ It generates:
 A Quarkus application uses the https://github.com/smallrye/smallrye-config[SmallRye Config] API to provide all
 mechanisms related with configuration.
 
-By default, Quarkus reads configuration properties from <<config-reference.adoc#configuration-sources,several sources>>.
+By default, Quarkus reads configuration properties from xref:config-reference.adoc#configuration-sources[several sources].
 For the purpose of this guide, we will use an application configuration file located in `src/main/resources/application.properties`.
+
 Edit the file with the following content:
 
 .application.properties

docs/src/main/asciidoc/doc-reference.adoc

@@ -254,7 +254,45 @@ When cross-referencing content, always use the inter-document `xref:` syntax and
 ----
 xref:{doc-guides}/doc-concept.adoc[Quarkus Documentation concepts] <1>
 ----
-<1> The cross reference starts with `xref:`, uses a cross-reference source attribute(`\{doc-guides}`), and provides a readable description: `[Quarkus Documentation concepts]`.
+<1> The cross-reference starts with `xref:`, uses a cross-reference source attribute(`\{doc-guides}`), and provides a readable description: `[Quarkus Documentation concepts]`.
+
+=== Anchors
+
+Quarkus documentation provides several ways a contributor can create and call anchors.
+To reach consistency and a better single-sourcing experience with Quarkus documentation, we ask contributors to use the `xref` approach for documenting and calling anchors.
+
+.Example
+* An anchor to a chapter inside the same `.adoc` file
+** Create an ID anchor:
++
+[source,asciidoc]
+--
+ [[<anchor-ID>]]
+--
+
+** Call the anchor
++
+[source,asciidoc]
+--
+xref:<anchor-ID>[]
+--
+
+* A cross-file anchor
+** Create an ID anchor:
++
+[source,asciidoc]
+--
+[[<anchor-ID>]]
+--
+
+** Call the anchor
++
+[source,asciidoc]
+--
+xref:<target-file>.adoc#<anchord-ID>[]
+--
+
+NOTE: The `[]` part of your `xref` anchors sets up a desired anchor label in cases where the default label does not fit the content.
 
 === Reference source code 
 

docs/src/main/asciidoc/getting-started.adoc

@@ -45,7 +45,7 @@ This guide also covers the testing of the endpoint.
 
 == Solution
 
-We recommend that you follow the instructions from <<bootstrapping-the-project,Bootstrapping project>> and onwards to create the application step by step.
+We recommend that you follow the instructions from xref:bootstrapping-the-project[Bootstrapping project] and onwards to create the application step by step.
 
 However, you can go right to the completed example.
 
@@ -69,12 +69,12 @@ For Linux & MacOS users
 :create-app-code:
 include::{includes}/devtools/create-app.adoc[]
 
-For Windows users
+For Windows users:
 
 - If using cmd , (don't use backward slash `\` and put everything on the same line)
 - If using Powershell , wrap `-D` parameters in double quotes e.g. `"-DprojectArtifactId=getting-started"`
 
-It generates the following in  `./getting-started`:
+It generates the following in `./getting-started`:
 
 * the Maven structure
 * an `org.acme.GreetingResource` resource exposed on `/hello`

docs/src/main/asciidoc/gradle-tooling.adoc

@@ -315,7 +315,7 @@ Then, attach your debugger to `localhost:5005`.
 
 == Import in your IDE
 
-Once you have a <<project-creation, project generated>>, you can import it in your favorite IDE.
+Once you have a xref:project-creation[project generated], you can import it in your favorite IDE.
 The only requirement is the ability to import a Gradle project.
 
 **Eclipse**

docs/src/main/asciidoc/hibernate-orm.adoc

@@ -98,11 +98,11 @@ They will often map to Hibernate ORM configuration properties but could have dif
 
 Also, Quarkus will set many Hibernate ORM configuration settings automatically, and will often use more modern defaults.
 
-Please see below section <<hibernate-configuration-properties, Hibernate ORM configuration properties>> for the list of properties you can set in `{config-file}`.
+For a list of the items that you can set in `{config-file}`, see xref:hibernate-configuration-properties[Hibernate ORM configuration properties].
 
 An `EntityManagerFactory` will be created based on the Quarkus `datasource` configuration as long as the Hibernate ORM extension is listed among your project dependencies.
 
-The dialect will be selected based on the JDBC driver - unless you set one explicitly.
+Unless you set one explicitly, the dialect will be selected based on the JDBC driver.
 
 You can then happily inject your `EntityManager`:
 
@@ -181,7 +181,7 @@ include::{generated-dir}/config/quarkus-hibernate-orm.adoc[opts=optional, levelo
 
 [NOTE]
 ====
-Do not mix <<persistence-xml,`persistence.xml`>> and `quarkus.hibernate-orm.*` properties in `{config-file}`.
+Do not mix xref:persistence-xml[`persistence.xml`] and `quarkus.hibernate-orm.*` properties in `{config-file}`.
 Quarkus will raise an exception.
 Make up your mind on which approach you want to use.
 
@@ -450,7 +450,7 @@ the https://jakarta.ee/specifications/persistence/3.0/jakarta-persistence-spec-3
 or the http://hibernate.org/dtd/hibernate-mapping-3.0.dtd[`hbm.xml` format (specific to Hibernate ORM, deprecated)]:
 
 * in `application.properties` through the (build-time) link:#quarkus-hibernate-orm_quarkus.hibernate-orm.mapping-files[`quarkus.hibernate-orm.mapping-files`] property.
-* in <<persistence-xml,`persistence.xml`>> through the `<mapping-file>` element.
+* in xref:persistence-xml[`persistence.xml`] through the `<mapping-file>` element.
 
 XML mapping files are parsed at build time.
 
@@ -769,22 +769,22 @@ configure your datasource as in the above examples and it will set up Hibernate
 More details about this connection pool can be found in xref:datasource.adoc[Quarkus - Datasources].
 
 Second Level Cache::
-as explained above in section <<caching,Caching>>, you don't need to pick an implementation.
+As explained earlier in the xref:caching[Caching] section, you don't need to pick an implementation.
 A suitable implementation based on technologies from link:https://infinispan.org/[Infinispan] and link:https://github.com/ben-manes/caffeine[Caffeine] is included as a transitive dependency of the Hibernate ORM extension, and automatically integrated during the build.
 
 === Limitations
 
 XML mapping with duplicate files in the classpath::
-<<xml-mapping,XML mapping>> files are expected to have a unique path.
-+
+xref:xml-mapping[XML mapping] files are expected to have a unique path.
+
 In practice, it's only possible to have duplicate XML mapping files in the classpath in very specific scenarios.
-For example, if two JARs include a `META-INF/orm.xml` file (with the exact same path, but in different JARs),
+For example, if two JARs include a `META-INF/orm.xml` file (with the same path but in different JARs),
 then the mapping file path `META-INF/orm.xml` can only be referenced from a `persistence.xml`
 **in the same JAR as the `META-INF/orm.xml` file**.
 
 JMX::
 Management beans are not working in GraalVM native images;
-therefore Hibernate's capability to register statistics and management operations with the JMX bean is disabled when compiling into a native image.
+therefore, Hibernate's capability to register statistics and management operations with the JMX bean is disabled when compiling into a native image.
 This limitation is likely permanent, as it's not a goal for native images
 to implement support for JMX. All such metrics can be accessed in other ways.
 
@@ -793,18 +793,17 @@ Hibernate ORM's capability to integrate with JACC is disabled when building Graa
 as JACC is not available - nor useful - in native mode.
 
 Binding the Session to ThreadLocal context::
-It is not possible to use the `ThreadLocalSessionContext` helper of Hibernate ORM as support for it is not implemented.
-Since Quarkus provides out of the box support for CDI, we believe using injection or programmatic CDI lookup to be a better approach.
+It is impossible to use the `ThreadLocalSessionContext` helper of Hibernate ORM as support for it is not implemented.
+Since Quarkus provides out-of-the-box CDI support, injection or programmatic CDI lookup is a better approach.
 This feature also didn't integrate well with reactive components and more modern context propagation techniques, making us believe this legacy feature has no future.
-If you badly need to bind it to a ThreadLocal it should be trivial to implement in your own code.
+If you badly need to bind it to a ThreadLocal, it should be trivial to implement in your own code.
 
 JNDI::
 The JNDI technology is commonly used in other runtimes to integrate different components.
-A common use case is Java Enterprise servers to bind the TransactionManager and the Datasource components to a name, and then have Hibernate ORM
-configured to look these components up by name.
-But in Quarkus this use case doesn't apply as components are injected directly, making JNDI support an unnecessary legacy.
-As a precaution, to avoid unexpected use of JNDI, the whole support for JNDI has been disabled in the Hibernate ORM extension for Quarkus.
-This is both a security precaution and an optimisation.
+A common use case is Java Enterprise servers to bind the TransactionManager and the Datasource components to a name and then have Hibernate ORM configured to look these components up by name.
+But in Quarkus, this use case doesn't apply as components are injected directly, making JNDI support an unnecessary legacy.
+To avoid unexpected use of JNDI, full support for JNDI has been disabled in the Hibernate ORM extension for Quarkus.
+This is both a security precaution and an optimization.
 
 === Other notable differences
 
@@ -901,7 +900,7 @@ public class CustomTenantResolver implements TenantResolver {
 <1> Annotate the TenantResolver implementation with the `@PersistenceUnitExtension` qualifier
 to tell Quarkus it should be used in the default persistence unit.
 +
-For <<multiple-persistence-units,named persistence units>>, use `@PersistenceUnitExtension("nameOfYourPU")`.
+For xref:multiple-persistence-units[named persistence units], use `@PersistenceUnitExtension("nameOfYourPU")`.
 <2> The bean is made `@RequestScoped` as the tenant resolution depends on the incoming request.
 
 From the implementation above, tenants are resolved from the request path so that in case no tenant could be inferred, the default tenant identifier is returned.
@@ -1065,7 +1064,7 @@ INSERT INTO known_fruits(id, name) VALUES (3, 'Blackberries');
 If you need a more dynamic configuration for the different tenants you want to support and don't want to end up with multiple entries in your configuration file,
 you can use the `io.quarkus.hibernate.orm.runtime.tenant.TenantConnectionResolver` interface to implement your own logic for retrieving a connection.
 Creating an application-scoped bean that implements this interface
-and annotating it with `@PersistenceUnitExtension` (or `@PersistenceUnitExtension("nameOfYourPU")` for a <<multiple-persistence-units,named persistence unit>>)
+and annotating it with `@PersistenceUnitExtension` (or `@PersistenceUnitExtension("nameOfYourPU")` for a xref:multiple-persistence-units[named persistence unit])
 will replace the current Quarkus default implementation `io.quarkus.hibernate.orm.runtime.tenant.DataSourceTenantConnectionResolver`.
 Your custom connection resolver would allow for example to read tenant information from a database and create a connection per tenant at runtime based on it.
 
@@ -1090,7 +1089,7 @@ public static class MyInterceptor extends EmptyInterceptor { // <2>
 <1> Annotate the interceptor implementation with the `@PersistenceUnitExtension` qualifier
 to tell Quarkus it should be used in the default persistence unit.
 +
-For <<multiple-persistence-units,named persistence units>>, use `@PersistenceUnitExtension("nameOfYourPU")`
+For xref:multiple-persistence-units[named persistence units], use `@PersistenceUnitExtension("nameOfYourPU")`
 <2> Either extend `org.hibernate.EmptyInterceptor` or implement `org.hibernate.Interceptor` directly.
 <3> Implement methods as necessary.
 
@@ -1132,5 +1131,5 @@ public class MyStatementInspector implements StatementInspector { // <2>
 <1> Annotate the statement inspector implementation with the `@PersistenceUnitExtension` qualifier
 to tell Quarkus it should be used in the default persistence unit.
 +
-For <<multiple-persistence-units,named persistence units>>, use `@PersistenceUnitExtension("nameOfYourPU")`
+For xref:multiple-persistence-units[named persistence units], use `@PersistenceUnitExtension("nameOfYourPU")`
 <2> Implement `org.hibernate.engine.jdbc.spi.StatementInspector`.

docs/src/main/asciidoc/hibernate-reactive.adoc

@@ -102,7 +102,7 @@ Also, Quarkus will set many Hibernate Reactive configuration settings automatica
 
 WARNING: Configuring Hibernate Reactive using the standard `persistence.xml` configuration file is not supported.
 
-Please, see section <<hr-configuration-properties, Hibernate Reactive configuration properties>> for the list of properties you can set in `{config-file}`.
+See section xref:hr-configuration-properties[Hibernate Reactive configuration properties] for the list of properties you can set in `{config-file}`.
 
 A `Mutiny.SessionFactory` will be created based on the Quarkus `datasource` configuration as long as the Hibernate Reactive extension is listed among your project dependencies.