diff --git a/base/src/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy b/base/src/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy index 7c53cfe94..d21e296b0 100644 --- a/base/src/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy +++ b/base/src/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy @@ -52,7 +52,8 @@ class AbstractImplementationEngineExtension tag::extension-property[] attributes:: Asciidoctor attributes. Use `attributes` to append and `setAttributes` to replace any current attributes with a new set. - Attribute values are lazy-evaluated to strings. See <> for more detail. + Attribute values are lazy-evaluated to strings. + See <> for more detail. end::extension-property[] ------------------------- */ diff --git a/docs/src/docs/asciidoc/attributes.adoc b/docs/src/docs/asciidoc/attributes.adoc index 501a75d3a..9750e96d5 100644 --- a/docs/src/docs/asciidoc/attributes.adoc +++ b/docs/src/docs/asciidoc/attributes.adoc @@ -2,7 +2,8 @@ :project-full-path: asciidoctor/asciidoctor-gradle-plugin :plugin-name: Asciidoctor Gradle plugin :asciidoc-url: https://asciidoc.org -:asciidoctor-docs: https://docs.asciidoctor.org/asciidoctor/latest/ +:asciidoc-docs: https://docs.asciidoctor.org/asciidoc/latest +:asciidoctor-docs: https://docs.asciidoctor.org/asciidoctor/latest :asciidoctor-maven-plugin-name: Asciidoctor Maven Plugin :asciidoctor-maven-plugin-url: https://github.com/asciidoctor/asciidoctor-maven-plugin :asciidoctor-url: https://asciidoctor.org diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/src/docs/asciidoc/index.adoc index f4f2736a0..17251c2ad 100644 --- a/docs/src/docs/asciidoc/index.adoc +++ b/docs/src/docs/asciidoc/index.adoc @@ -33,13 +33,13 @@ include::parts/asciidoctorj-epub-plugin.adoc[] include::parts/asciidoctorj-revealjs-plugin.adoc[] -// include::parts/asciidoctorj-leanpub-plugin.adoc[] +//! include::parts/asciidoctorj-leanpub-plugin.adoc[] include::parts/asciidoctor-diagram.adoc[] include::parts/asciidoctorj-gems-plugin.adoc[] -//include::parts/kindlegen-plugin.adoc[] +//! include::parts/kindlegen-plugin.adoc[] include::parts/asciidoctorj-custom-extensions.adoc[] diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc index dbba3bc8f..0b3ec6ccd 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc @@ -48,8 +48,7 @@ The following common entities can also be set: include::{plugin-base}/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy[indent=0,tags="extension-property"] // TODO: Split attributes into a standalone section that is not part of base plugin. -[[attributes,Setting Attributes]] -[[options,Setting Options]] +[#options-and-attributes] == Options & Attributes The following options may be set using the extension's `options` property @@ -108,10 +107,9 @@ These attributes may be overridden by explicit user input. Refer to the {asciidoctor-docs}[Asciidoctor documentation] to learn more about these options and attributes. -Attribute values defined on the build file will win over values defined on the documents themselves. You can change -this behavior by appending an `@` at the end of the value when defined in the build file. Please refer to -link:{asciidoctor-userguide}#attribute-assignment-precedence[Attribute assignment precedence, window="_blank"] -for more information. +Attribute values defined on the build file will win over values defined on the documents themselves. +You can change this behavior by appending an `@` at the end of the value when defined in the build file. +Please refer to link:{asciidoc-docs}/attributes/assignment-precedence#altering-the-assignment-precedence[Attribute assignment precedence, window="_blank"] for more information. [[asciidoctorj-modules,{asciidoctorj-name} Modules]] == Versions of modules diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc index fe894d560..23d377420 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc +++ b/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc @@ -32,7 +32,7 @@ The `AsciidoctorRevealJSTask` task type has the following additional methods: [horizontal] revealjsOptions:: Configure special Reveal.js options. - Can be configured via Closure or Action. See <> for more details. + Can be configured via Closure or Action. See <> for more details. templateDir:: Location where the template directory will be located on disk before Asciidoctor processing starts. theme:: The Reveal.js theme to use. The theme must match one from the template. @@ -56,8 +56,8 @@ revealjs { If not specified, sensible defaults are provided. -== Reveal.js Options [[RevealJsOptions]] +== Reveal.js Options Various options can be configured for Reveal.js. Although these can be set as attributes directly, it is far better to set them on the task as advantage can be taken of Gradle task caching and file resolving. diff --git a/docs/src/docs/asciidoc/parts/common-task-configuration.adoc b/docs/src/docs/asciidoc/parts/common-task-configuration.adoc index a66aec581..68ac0bdfd 100644 --- a/docs/src/docs/asciidoc/parts/common-task-configuration.adoc +++ b/docs/src/docs/asciidoc/parts/common-task-configuration.adoc @@ -5,7 +5,8 @@ All Asciidoctor tasks will have the following methods and properties: .Properties and methods common all {asciidoctorj-name} tasks [horizontal] 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. + This allows extensive flexibility. + Any thing that can be configured in the global `asciidoctorj` extension can also be configured here. attributes:: A shortcut for `asciidoctorj.attributes` and `asciidoctorjs.attributes`. baseDir:: Base directory for asciidoctor document conversion and root document inclusion. The base directory will be the project directory by default, but can be set to any other directory. @@ -29,10 +30,12 @@ outputDir:: where generated docs go. Type: File, but any object convertible with `project.file` can be passed. Default: `$buildDir/asciidoc`. parallelMode:: Specifies whether each backend or other variant of a converting tasks should be run in parallel or sequential. - Sequential conversions might have less initialisation overhead, but may suffer from `gemPath` and extension pollution. Default: `true` (parallel). + Sequential conversions might have less initialisation overhead, but may suffer from `gemPath` and extension pollution. + Default: `true` (parallel). resources:: specify which additional files (image etc.) must be copied to output directory using a http://www.gradle.org/docs/current/javadoc/org/gradle/api/file/CopySpec.html[CopySpec]. -secondarySources: Specify which source files should be monitor for change. These are typically files which are included by top-level files as well as doctype files. +secondarySources:: Specify which source files should be monitored for change. + These are typically files which are included by top-level files as well as doctype files. Default: All files in sourceDir which matches `getDefaultSourceDocumentPattern()` as well as doctype files. sourceDir:: where the asciidoc sources are. Use either `sourceDir path`, `setSourceDir path` or `sourceDir=path` @@ -41,9 +44,13 @@ sourceDir:: where the asciidoc sources are. sources:: Specify which Asciidoctor source files to include as toplevel documents. It uses an http://www.gradle.org/docs/current/javadoc/org/gradle/api/tasks/util/PatternSet.html[Ant-style PatternSet]. useIntermediateWorkDir:: Use an intermediate work directory for sources ances. - Some extensions such as `ditaa` will write content into the source directory. In order to keep the project source directory pristine an intermediate work directory can be used. All sources and resources will be copied there prior the executing Asciidoctor. + Some extensions such as `ditaa` will write content into the source directory. + In order to keep the project source directory pristine an intermediate work directory can be used. + All sources and resources will be copied there prior the executing Asciidoctor. withIntermediateArtifacts:: Add intermediate artifacts to output directory. - If the document conversion process creates intermediate artifacts which needs to be added to the output directory, then the pattern set with a closure or `Action`. This implies `useIntermediateWorkDir`. An example of such a case is the use of `ditaa`. + If the document conversion process creates intermediate artifacts which needs to be added to the output directory, then the pattern set with a closure or `Action`. + This implies `useIntermediateWorkDir`. + An example of such a case is the use of `ditaa`. IMPORTANT: You will have to configure the properties for each plugin as they are not inherited from one to another. For example you will have to configure `languages` for both `org.asciidoctor.jvm.convert` and `org.asciidoctor.jvm.pdf` plugins if you want multi language pdf and html. @@ -61,7 +68,7 @@ backends:: the backends to use. separateOutputDirs:: specifies whether each backend should use a separate subfolder under `outputDir`. Default: `true` -=== Defining Sources +== Defining Sources The plugin will search for sources under `sourceDir`. Sources may have any of the following extensions in order to be discovered: @@ -104,7 +111,7 @@ tasks { Paths defined in this PatternSet are resolved relative to the `sourceDir`. -=== Processing Auxiliary Files +== Processing Auxiliary Files Some backends require that additional files be copied across. The most common example are images for HTML backends. For this the `resources` method is used. It is provided with a closure that configures an org.asciidoctor.gradle.jvm.epub.internal @@ -181,7 +188,7 @@ If you do not want this behaviour, then it can be turned off by doing copyNoResources() ---- -If you are using multiple languages and you have identical resource patterns for each languages within `sourceDir/${lang}` you need to explicitly declare those on a per-language basis: +If you are using multiple languages and you have identical resource patterns for each language within `sourceDir/${lang}` you need to explicitly declare those on a per-language basis: [source,groovy,role="primary"] .build.gradle @@ -222,11 +229,13 @@ asciidoctor { == 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. +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. == Source language support -Some scenarios work on a source set of documents in a primary language and then translations of those sources into other languages. The Gradle plugin simplifies this scenario by allowing a structure such as +Some scenarios work on a source set of documents in a primary language and then translations of those sources into other languages. +The Gradle plugin simplifies this scenario by allowing a structure such as [source] ---- @@ -247,7 +256,9 @@ asciidoctor { } ---- -Gradle will then process both the `en` and the `es` source set and output to the output directory using the same languages names. Intermediate working directories and multiple backends are also covered. In this case the `lang` attribute will be injected with the specific language as the value. +Gradle will then process both the `en` and the `es` source set and output to the output directory using the same languages names. +Intermediate working directories and multiple backends are also covered. +In this case the `lang` attribute will be injected with the specific language as the value. It is also possible to specify additional attributes that will only be added when a specific language is processed @@ -260,17 +271,18 @@ asciidoctorj { // <1> asciidoctorjs { // <2> attributesForLang 'en', langName : 'English' - attributesForLang 'ca', langName : 'Catala' + attributesForLang 'ca', langName : 'Catala'F } ---- <1> Configuration when using {asciidoctorj-name} <2> Configuration when using {asciidoctorjs-name} -=== Choosing a Process Mode for {asciidoctorj-name} +== Choosing a Process Mode for {asciidoctorj-name} All {asciidoctorj-name}-based tasks can control how Asciidoctor conversions are being run via the `inProcess` property. This is early days, and a choice for your build will depend very much on your context, but the following has already become clear: * `IN_PROCESS` and `OUT_OF_PROCESS` should theoretically run faster, especially if you continuously rebuild the same documentation. Gradle workers are the underlying implementation for these two options * The safe option is always `JAVA_EXEC`. For lower memory consumption this is by far the safer option. (It is also the only way we can get the Windows-based tests for this plugin to complete on Appveyor & Travis CI). It you run a lot of builds the penalty start-up time might become an issue for you. -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. +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. diff --git a/jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy b/jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy index 00b57d168..0467565b7 100644 --- a/jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy +++ b/jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy @@ -481,7 +481,8 @@ class AsciidoctorJExtension extends AbstractImplementationEngineExtension { tag::extension-property[] 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. See <> for more details. + Options are evaluated as late as possible. + See <> for more details. end::extension-property[] ------------------------- */