* <ul>
 *   <li>User and system properties for interpolation</li>
 *   <li>Session start time information</li>
 *   <li>Project directory structures</li>
 * </ul>
 *
 * <p>Requests can optionally carry trace information through {@link RequestTrace} to support:
 * <ul>
 *   <li>Debugging and troubleshooting of request flows</li>
 *   <li>Audit logging of operations</li>

     * <ul>
     *   <li>For included dependencies: {@code groupId:artifactId:version[:scope] (details)}</li>
     *   <li>For omitted dependencies: {@code (groupId:artifactId:version[:scope] - details)}</li>
     * </ul>
     * Where details may include:
     * <ul>
     *   <li>Version management information (if the version was managed from a different version)</li>

 * <ul>
 *   <li>{@code merge} (default): Merges attributes and values</li>
 *   <li>{@code override}: Completely replaces the element</li>
 *   <li>{@code remove}: Removes the element</li>
 * </ul>
 *
 * <p>For complex XML structures, combining can also be done based on:</p>
 * <ul>
 *   <li>ID: Using the {@code combine.id} attribute</li>

/**
 * Transforms userguide source into docbook, replacing custom XML elements.
 *
 * Takes the following as input:
 * <ul>
 * <li>A source docbook XML file.</li>
 * <li>Meta-info about the canonical documentation for each class referenced in the document, as produced by {@link gradlebuild.docs.dsl.docbook.AssembleDslDocTask}.</li>
 * </ul>
 *
 */
@CacheableTask
abstract class UserGuideTransformTask extends DefaultTask {

 *
 * Hierarchy:
 * <ul>
 * <li>{@link org.apache.maven.cling.invoker.LookupInvoker} is the "basis", the common ground of all Maven Tools</li>
 * <li>extended by {@link org.apache.maven.cling.invoker.mvn.MavenInvoker} is the "mvn Tool"</li>
 * <li>extended by {@link org.apache.maven.cling.invoker.mvnenc.EncryptInvoker} is the "mvnenc Tool"</li>

 * <li>POM: Repositories can be specified in the {@code pom.xml} file under the {@code <repositories>} and {@code <pluginRepositories>} sections.</li>
 * <li>Settings: the {@code settings.xml} can be used to provide additional repositories in the three level of settings (user, project, installation).</li>
 * </ol>

 *
 * <p>When resolving dependencies, Maven follows this order:</p><ol>
 * <li>Check Local Repository: Maven first checks if the artifact is available in the local repository.</li>
 * <li>Check Remote Repositories: If the artifact is not found locally, Maven queries the configured remote repositories in the order they are listed.</li>

     * <li>The parent uses aggregation and refers to the child via the modules section</li>
     * <li>The module path to the child is considered to
     * point at the POM rather than its base directory if the path ends with ".xml" (ignoring case)</li>
     * <li>The name of the child's base directory matches the artifact id of the child.</li>
     * </ul>

            Type of toolchain:<ul>
            <li>{@code jdk} for <a
            href="https://maven.apache.org/plugins/maven-toolchains-plugin/toolchains/jdk.html">JDK Standard Toolchain</a>,</li>
            <li>other value for <a
            href="https://maven.apache.org/plugins/maven-toolchains-plugin/toolchains/custom.html">Custom Toolchain</a></li>
            </ul>
          </description>

     * <p>The implementation supports indexed, nested and mapped properties.</p>
     * <ul>
     * <li>nested properties should be defined by a dot, i.e. "user.address.street"</li>
     * <li>indexed properties (java.util.List or array instance) should be contains <code>(\\w+)\\[(\\d+)\\]</code>
     * pattern, i.e. "user.addresses[1].street"</li>
     * <li>mapped properties should be contains <code>(\\w+)\\((.+)\\)</code> pattern,