diff --git a/README.adoc b/README.adoc index 0ddb762..41d8266 100644 --- a/README.adoc +++ b/README.adoc @@ -10,16 +10,13 @@ ifdef::env-browser[] :source-highlighter: highlight.js :icons: font endif::[] -ifdef::env-github,env-browser[] -:toc: preamble -endif::[] ifdef::env-github[] :badges: -:!toc-title: endif::[] // Refs :asciidoclet-version: 1.5.6 :asciidoclet-src-ref: https://github.com/asciidoctor/asciidoclet +:asciidoclet-docs-ref: https://docs.asciidoctor.org/asciidoclet/latest/ :asciidoclet-javadoc-ref: https://www.javadoc.io/doc/org.asciidoctor/asciidoclet/{asciidoclet-version} :asciidoclet-release-ref: https://asciidoctor.org/news/2014/09/09/asciidoclet-1.5.0-released/ :asciidoc-ref: https://asciidoc.org @@ -44,6 +41,8 @@ AsciiDoc straddles the line between readable markup and beautifully rendered con Asciidoclet incorporates an AsciiDoc renderer (Asciidoctor via the {asciidoctor-java-ref}[Asciidoctor Java integration] library) into a simple Doclet that enables AsciiDoc formatting within Javadoc comments and tags. +See the {asciidoclet-docs-ref}[full documentation] for more details. + == Example Here's an example of a class with traditional Javadoc. @@ -105,12 +104,10 @@ public class Asciidoclet extends Doclet { The result is readable source and beautifully rendered Javadocs, the best of both worlds! -// tag::usage[] -== Usage +== Quick Start -Run Javadoc with the `org.asciidoctor.Asciidoclet` doclet class. -Some examples for common build systems are shown below. -See <> for supported options. +Run the standard `javadoc` build task for your build system specifying the +`org.asciidoctor.Asciidoclet` doclet class. Some examples for common build systems are shown below. === Maven @@ -138,12 +135,13 @@ Asciidoclet may be used via a `maven-javadoc-plugin` doclet: --attribute "title-link=https://example.com[${project.name} ${project.version}]" + ---- - + === Gradle -Asciidoclet may be used via a doclet in the `Javadoc` task: +Asciidoclet may be used via a doclet in the `javadoc` task: [source,groovy] ---- @@ -167,118 +165,12 @@ javadoc { } ---- <1> Option names passed to Gradle's `javadoc` task must omit the leading "-", so here "-base-dir" means "--base-dir". -See <> below. <2> Gradle's `javadoc` task does not allow multiple occurrences of the same option. Multiple attributes can be specified in a single string, separated by commas. -=== Ant -// Some of us still use Ant, alright?! -Asciidoclet may be used via a doclet element in Ant's `javadoc` task: - -[source,xml] ----- - - - - - - - - ----- - -<1> Assumes a path reference has been defined for Asciidoclet and its dependencies, e.g. -using https://ant.apache.org/ivy/[Ivy] or similar. - -=== Doclet Options -// tag::doclet-options[] - ---base-dir :: -Sets the base directory that will be used to resolve relative path names in Asciidoc `include::` directives. -This should be set to the project's root directory. - --a, --attribute "name[=value], ...":: -Sets https://asciidoctor.org/docs/user-manual/#attributes[document attributes^] that will be expanded in Javadoc comments. -The argument is a string containing a single attribute, or multiple attributes separated by commas. -+ -This option may be used more than once, for example: `-a name=foo -a version=1`. -+ -Attributes use the same syntax as Asciidoctor command-line attributes: -+ --- -* `name` sets the attribute (with an empty value) -* `name=value` assigns `value` to the attribute. Occurrences of `\{name}` in the Javadoc will be replaced by this value. -* `name=value@` assigns `value` to the attribute, unless the attribute is defined in the attributes file or Javadoc. -* `name!` unsets the attribute. --- -+ -The document attribute `javadoc` is set automatically by the doclet. -This can be used for conditionally selecting content when using the same Asciidoc file for Javadoc and other documentation. - ---attributes-file :: -Reads https://asciidoctor.org/docs/user-manual/#attributes[document attributes^] from an Asciidoc file. -The attributes will be expanded in Javadoc comments. -+ -If `` is a relative path name, it is assumed to be relative to the `--base-dir` directory. -+ -Attributes set by the `-a`/`--attribute` option take precedence over those in the attributes file. - --r, --require ,...:: -Make the specified RubyGems library available to Asciidoctor's JRuby runtime, for example `-r asciidoctor-diagram`. -+ -This option may be specified more than once. -Alternatively multiple library names may be specified in a single argument, separated by commas. - ---gem-path :: -Sets the `GEM_PATH` for Asciidoctor's JRuby runtime. -This option is only needed when using the `--require` option to load additional gems on the `GEM_PATH`. - --overview :: -Overview documentation can be generated from an Asciidoc file using the standard `-overview` option. -Files matching [x-]`*.adoc`, [x-]`*.ad`, [x-]`*.asciidoc` or [x-]`*.txt` are processed by Asciidoclet. -Other files are assumed to be HTML and will be processed by the standard doclet. - -// end::doclet-options[] -// end::usage[] - -=== Log Warning - -Currently there is a intermittent benign warning message that is emitted during a run of Asciidoclet stating the following: - -.... -WARN: tilt autoloading 'tilt/haml' in a non thread-safe way; explicit require 'tilt/haml' suggested. -.... - -Unfortunately, until the underlying library removes this warning message, it will be logged during the build. - -== Additional Features - -Make sure to see {asciidoclet-release-ref}[Asciidoclet 1.5.0 Release Notes] for additional features not documented here. - -== Resources and help - -For more information: - -* {asciidoclet-release-ref}[Asciidoclet 1.5.0 Release Notes] -* {asciidoclet-src-ref}[Asciidoclet Source Code] -* {asciidoclet-javadoc-ref}[Asciidoclet JavaDoc] -* {asciidoclet-issues-ref}[Asciidoclet Issue Tracker] -* {asciidoctor-src-ref}[Asciidoctor Source Code] -* {asciidoctor-java-src-ref}[Asciidoctor Java Integration Source Code] - -If you have questions or would like to help develop this project, please join the {discuss-ref}[Asciidoctor discussion list]. - -ifndef::env-site[] -== Powered by Asciidoclet - -We have a <> page. -If you have an example of nifty JavaDoc powered by Asciidoclet, please send us a pull request. -endif::[] +See the {asciidoclet-docs-ref}[documentation] for more details. == License - .... Copyright (C) 2013-2015 John Ericksen