Merge pull request #372 from asciidoctor/development-2.0

Release 2.2.0

README.adoc

@@ -1,7 +1,7 @@
 = Asciidoctor Gradle Plugin
 Andres Almiray <https://github.com/aalmiray[@aalmiray]>
-:version: 2.1.0
-:version-published: 2.0.0
+:version: 2.2.0
+:version-published: 2.2.0
 :asciidoc-url: http://asciidoc.org
 :asciidoctor-url: http://asciidoctor.org
 :issues: https://github.com/asciidoctor/asciidoctor-maven-plugin/issues
@@ -155,14 +155,12 @@ attributes:: {asciidoctorj-epub-name} attributes.
   Attribute values are lazy-evaluated to strings.
 attributeProvider:: Register an additional provider of attributes.
   Attribute providers are a means of adding attributes that will not affect the up-to-date status of tasks.
-epubVersion:: {asciidoctorj-epub-name} version.
-  If not specified asciidoctorj-epub will not be on the classpath. If you plan to use the EPUB backend, then you need to set a version here.
-extensions:: Groovy DSL extensions.
-  Use `extensions` to add one or more extensions. Use `setExtensions` to replace the current set of extensions with a new set.
+docExtensions:: Groovy DSL extensions.
+  Use `docExtensions` to add one or more extensions. Use `setDocExtensions` to replace the current set of extensions with a new set.
   Extensions can be any kind of object that is serialisable, although in most cases they will be strings or files.
   If extensions are detached dependencies, they will not be serialised, but rather will be placed on the classpath in
   order that {asciidoctorj-name} can pick them up automatically.
-fatalWarnings: Patterns for {asciidoctorj-name} log messages that shuold be treated as fatal errors.
+fatalWarnings: Patterns for {asciidoctorj-name} log messages that should be treated as fatal errors.
   The list is empty be default. Use `setFatalWarnings` to clear any existing patterns or to decouple a task's configuration from the global
   configuration. Use `fatalWarnings` to add more patterns. Pass `missingIncludes()` to add the common use-case of
   missing include files.
@@ -171,18 +169,15 @@ gemPaths:: One or more gem installation directories (separated by the system pat
   Use `asGemPath` to obtain a path string, separated by platform-specific separator.
   Type: FileCollection, but any collection of objects convertible with `project.files` can be passed
   Default: empty
-groovyDslVersion:: Version of Groovy Extensions DSL.
-  If not specified and no extensions are specified, Groovy DSL will not be used. However, if any extensions are added without setting an explicit version and default version will be used.
 jrubyVersion:: Minimum version of JRuby to be used.
   The exact version that will be used could be higher due to {asciidoctorj-name} having a transitive dependency that is newer.
 logLevel:: The log level at which AsciidoctorJ will log.
   This is specified as a Gradle logging level. The plugin will translate it to the appropriate AsciidoctorJ logging level.
   Default is `project.logger.level`.
-options: {asciidoctorj-name} options.
+modules:: Configuration for version of specific compoenents and converters that can be used.
+options:: {asciidoctorj-name} options.
   Use `options` to append and `setOptions` to replace any current options with a new set.
   Options are evaluated as late as possible.
-pdfVersion:: {asciidoctorj-pdf-name} version.
-  If not specified asciidoctorj-pdf will not be on the classpath. If you plan to use the PDF backend, then you need to set a version here.
 requires:: The set of Ruby modules to be included.
   Use `requires` to append. Use `setRequires` or `requires=['name']` to overwrite.
   Default: empty.
@@ -196,7 +191,7 @@ version:: Asciidoctorj version.
 
 === Options & Attributes
 
-The following options may be set using the extensions' `options` property
+The following options may be set using the extension's `options` property
 
  * header_footer - boolean
  * template_dirs - List<String>
@@ -277,6 +272,49 @@ this behavior by appending an `@` at the end of the value when defined in the bu
 link:http://asciidoctor.org/docs/user-manual/#attribute-assignment-precedence[Attribute assignment precedence, window="_blank"]
 for more information.
 
+=== Versions of components
+
+The modules block currently supports four elements
+
+[source,groovy]
+.build.gradle
+----
+asciidoctorj {
+  modules {
+    pdf { // <1>
+      version '1.2.3'
+    }
+    epub { // <2>
+      version '1.2.3'
+    }
+    diagram { // <3>
+      version '1.2.3'
+    }
+    groovyDsl { // <4>
+      version '1.2.3'
+    }
+  }
+}
+----
+<1> {asciidoctorj-epub-name} version. If not specified asciidoctorj-epub will not be on the classpath. If you plan to use the EPUB backend and not using the EPUB plugin, then you need to set a version here.
+<2> {asciidoctorj-pdf-name} version. If not specified asciidoctorj-pdf will not be on the classpath. If you plan to use the PDF backend and not using the PDF plugin, then you need to set a version here.
+<3> See <<diagram,AsciidoctorJ Diagram>>,
+<4> Version of Groovy Extensions DSL. If not specified and no extensions are specified, Groovy DSL will not be used. However, if any extensions are added without setting an explicit version and default version will be used.
+
+
+When using the {kotlin-dsl} the same settings can be achieved use something similar `getModules().getPdf().version("1.2.3")`. In a similar fashion shortcuts can be achived in the {groovy-dsl}:
+
+[source,groovy]
+----
+asciidoctorj {
+  modules {
+    pdf.version '1.2.3'
+  }
+
+  modules.pdf.version '1.2.3'
+}
+----
+
 == AsciidoctorJ tasks
 
 All Asciidoctor tasks will have the following methods and properties:
@@ -286,6 +324,11 @@ All Asciidoctor tasks will have the following methods and properties:
 asciidoctorj:: a task extension which allows a task to extend of override global configuration for Asciidoctor tasks.
   This allow extensive flexibility. Any thing that can be configured in the global `asciidoctorj` extension can also be configured here.
 attributes:: A shortcut for `asciidoctorj.attributes`.
+baseDir:: Base directory for asciidoctor document conversion and root document inclusion.
+  The base directory will be the project directory, but default, but can be set to any other directory.
+baseDirFollowsSourceDir:: The base directory should be the same as the source directory even if the source directory is located within an intermediate working directory.
+baseDirIsProjectDir:: The base directory is always the current project directory.
+baseDirIsRootProjectDir:: The base directory is always the root project directory.
 configurations:: Specify additional configurations
   These configurations will be added to the classpath when the task is executed.
 copyAllResources:: Copy all resources to the output directory
@@ -446,10 +489,28 @@ All tasks can control how Asciidoctor conversions are being run via the `inProce
 
 NOTE: In certain cases the plugin will overrule your choice as it has some built-in rules for special cases. In such cases it will log a warning that it has done that.
 
-=== Include directives
+=== Include directives and base directory
 
 These plugins do not change the way link:https://asciidoctor.org/docs/user-manual/#include-resolution[include::] directive works, but it is important to note how setting `baseDir` will affect top level includes. It is recommended that you always use `{includedir}` as a prefix for the file path. This attribute is always set to the correct top-level folder where the sources will be located.
 
+However it is not practical for everyone to use `{includedir}` and as from 2.2.0 it is possible to add a strategy for controlling the base directory:
+
+[source,groovy]
+----
+asciidctor {
+    baseDirIsRootProjectDir() // <1>
+    baseDirIsProjectDir() // <2>
+    baseDirFollowsSourceDir() // <3>
+}
+----
+<1> The base directory is the root project directory.
+<2> The base directory is the current subproject directory.
+<3> The base directory will always the the same as the source directory. If an intermediate working directory is being used, the base directory will automatically point to that.
+
+=== Docinfo processing
+
+When using the `docinfo` attribute with `html` and `docbook` backends, it is recommended that `baseDirFollowsSourceDir()` is always set. This will ensure that the docinfo files are picked up correctly from the same directory that is the source directory.
+
 == The New AsciidoctorJ Plugin
 
 When applying `org.asciidoctor.jvm.convert` it creates a single task of type `org.asciidoctor.gradle.jvm.AsciidoctorTask` called `asciidoctor`.
@@ -535,6 +596,7 @@ ebookFormats:: The epub formats to generate.
 
 NOTE: KF8 formats cannot be generated under Windows at present.
 
+[[diagram]]
 == Using AsciidoctorJ Diagram
 
 The new plugins have built-in support for `asciidoctorj-diagram`. Simply add the following to the project or task extension and
@@ -543,7 +605,9 @@ diagramming will be available. If it is not set the `asciidoctorj-diagram` JAR w
 [source,groovy]
 ----
 asciidoctorj {
-    diagramVersion '1.5.4.1'
+    modules {
+       diagram.version '1.5.4.1'
+    }
 }
 ----
 
@@ -911,7 +975,7 @@ plugins {
 }
 
 asciidoctorj {
-    extensions project(':extension')
+    docExtensions project(':extension')
 }
 ----
 
@@ -922,13 +986,13 @@ In the less-common case where extension is not supplied via the default configur
 
 The next option is to define extensions directly in the build script.
 This approach is based on the project asciidoctorj-groovy-dsl that allows to define Asciidoctor extensions in Groovy.
-An extension is registered via the `extensions` element.
+An extension is registered via the `docExtensions` element.
 
 [source,groovy]
 .build.gradle
 ----
 asciidoctorj {
-    extensions {
+    docExtensions {
         block(name: "BIG", contexts: [":paragraph"]) {
             parent, reader, attributes ->
             def upperLines = reader.readLines()
@@ -949,7 +1013,7 @@ Groovy extensions can also be included as files.
 .build.gradle
 ----
 asciidoctorj {
-    extensions file('big.groovy')
+    docExtensions file('big.groovy')
 }
 ----
 

asciidoctor-gradle-base/src/intTest/groovy/org/asciidoctor/gradle/base/ApplyPluginSpec.groovy

@@ -20,7 +20,6 @@ import org.asciidoctor.gradle.base.internal.FunctionalSpecification
 class ApplyPluginSpec extends FunctionalSpecification {
 
     void 'Apply the base plugin in a Kotlin DSL'() {
-
         given:
         getKotlinBuildFile('')
 
@@ -32,7 +31,6 @@ class ApplyPluginSpec extends FunctionalSpecification {
     }
 
     void 'Apply the base plugin in a Groovy DSL'() {
-
         given:
         getGroovyBuildFile('', 'base')
 

asciidoctor-gradle-base/src/intTest/groovy/org/asciidoctor/gradle/base/internal/FunctionalSpecification.groovy

@@ -31,10 +31,15 @@ import static org.asciidoctor.gradle.testfixtures.jvm.FunctionalTestSetup.getOff
 
 class FunctionalSpecification extends Specification {
 
-    static
-    final String TEST_PROJECTS_DIR = System.getProperty('TEST_PROJECTS_DIR') ?: './asciidoctor-gradle-base/src/intTest/projects'
-    static
-    final String TEST_REPO_DIR = System.getProperty('OFFLINE_REPO') ?: './testfixtures/offline-repo/build/repo'
+    public static final String TEST_PROJECTS_DIR = System.getProperty(
+        'TEST_PROJECTS_DIR',
+        './asciidoctor-gradle-base/src/intTest/projects'
+    )
+
+    public static final String TEST_REPO_DIR = System.getProperty(
+        'OFFLINE_REPO',
+        './testfixtures/offline-repo/build/repo'
+    )
 
     @Rule
     TemporaryFolder testProjectDir
@@ -49,7 +54,7 @@ class FunctionalSpecification extends Specification {
         getGradleRunner(taskNames).withDebug(false)
     }
 
-    @SuppressWarnings(['FactoryMethodName', 'BuilderMethodWithSideEffects'])
+    @SuppressWarnings(['BuilderMethodWithSideEffects'])
     void createTestProject(String docGroup = 'normal') {
         FileUtils.copyDirectory(new File(TEST_PROJECTS_DIR, docGroup), testProjectDir.root)
     }
@@ -66,9 +71,9 @@ class FunctionalSpecification extends Specification {
             plugins {
                 id '${plugin}'
             }
-            
+
             ${offlineRepositories}
-            
+
             ${extraContent}
         """
         buildFile
@@ -80,7 +85,7 @@ class FunctionalSpecification extends Specification {
             plugins {
                 id("${plugin}")
             }
-            
+
             ${getOfflineRepositories(KOTLIN_DSL)}
 
             ${extraContent}

asciidoctor-gradle-base/src/main/groovy/org/asciidoctor/gradle/base/AsciidoctorBasePlugin.groovy

@@ -30,6 +30,4 @@ class AsciidoctorBasePlugin implements Plugin<Project> {
     void apply(Project project) {
         project.apply plugin: 'base'
     }
-}
-
-
+}

asciidoctor-gradle-base/src/main/groovy/org/asciidoctor/gradle/base/AsciidoctorModuleDefinition.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2013-2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.asciidoctor.gradle.base;
+
+/** Describes a converter.
+ *
+ * @since 2.2.0
+ */
+public interface AsciidoctorModuleDefinition {
+    /** Use the default version of this component
+     *
+     */
+    void use();
+
+    /** Set the version of the component to use.
+     *
+     * @param o Any object can can be converted to a String using
+     *          {@code org.ysb33r.grolifant.api.StringUtils.stringize}
+     */
+    void setVersion(Object o);
+
+    /** Declarative way in DSL to set the version of the component to use.
+     *
+     * @param o Any object can can be converted to a String using
+     *          {@code org.ysb33r.grolifant.api.StringUtils.stringize}
+     */
+    void version(Object o);
+
+    /** Version of the component
+     *
+     * @return Returns version to use, or {@code null} if no version was set.
+     *   The latter usually implies that the specific component is not needed.
+     */
+    String getVersion();
+}

asciidoctor-gradle-base/src/main/groovy/org/asciidoctor/gradle/base/AsciidoctorUtils.groovy

@@ -26,11 +26,17 @@ import org.ysb33r.grolifant.api.OperatingSystem
 
 import static groovy.lang.Closure.DELEGATE_FIRST
 
+/** Utility methods used internally by Asciidoctor plugins.
+ *
+ * @author Schalk W. Cronjé
+ *
+ * @since 2.0.0
+ */
 @CompileStatic
 class AsciidoctorUtils {
 
-    static final OperatingSystem OS = OperatingSystem.current()
-    static final String UNDERSCORE_LED_FILES = '**/_*'
+    public static final OperatingSystem OS = OperatingSystem.current()
+    public static final String UNDERSCORE_LED_FILES = '**/_*'
 
     static final Spec<? super File> ACCEPT_ONLY_FILES = new Spec<File>() {
         @Override
@@ -56,7 +62,8 @@ class AsciidoctorUtils {
 
         ft.visit { FileVisitDetails it ->
             if (it.name.startsWith('_')) {
-                throw new GradleException("Sources starting with '_' found. This is not allowed. Current sources are: ${ft.files}")
+                throw new GradleException("Sources starting with '_' found. This is not allowed. " +
+                    "Current sources are: ${ft.files}")
             }
         }
 
@@ -71,10 +78,10 @@ class AsciidoctorUtils {
      */
     static String normalizePath(String path) {
         if (OS.windows) {
-            path = path.replace(DOUBLE_BACKLASH, BACKLASH)
-            path = path.replace(BACKLASH, DOUBLE_BACKLASH)
+            path.replace(DOUBLE_BACKLASH, BACKLASH).replace(BACKLASH, DOUBLE_BACKLASH)
+        } else {
+            path
         }
-        path
     }
 
     /**