remkop · remkop · Sep 12, 2020 · Sep 11, 2020 · Sep 11, 2020 · Sep 11, 2020
diff --git a/docs/A-Whirlwind-Tour-of-Picocli.adoc b/docs/A-Whirlwind-Tour-of-Picocli.adoc
@@ -2,6 +2,10 @@
 :author: Remko Popma
 :source-highlighter: coderay
 :icons: font
+ifdef::env-github[]
+:note-caption: :information_source:
+:tip-caption: :bulb:
+endif::[]
 //:imagesdir: http://picocli.info
 
 

diff --git a/docs/autocomplete.adoc b/docs/autocomplete.adoc
@@ -10,6 +10,9 @@
 :source-highlighter: coderay
 :icons: font
 :imagesdir: images
+ifdef::env-github[]
+:tip-caption: :bulb:
+endif::[]
 
 [link=https://github.com/remkop/picocli]
 image::https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png[Fork me on GitHub,float="right"]

diff --git a/docs/build-great-native-cli-apps-in-java-with-graalvm-and-picocli.adoc b/docs/build-great-native-cli-apps-in-java-with-graalvm-and-picocli.adoc
@@ -7,6 +7,9 @@
 //:toclevels: 3
 //:imagesdir: https://picocli.info/images/
 :imagesdir: images/
+ifdef::env-github[]
+:tip-caption: :bulb:
+endif::[]
 // create variables for some link text used in article to prevent link mangling in PDF
 :ms-cpp-2015-redist: Microsoft Visual C++ 2015 Redistributable Update 3 RC
 :ms-cpp-2010-redist: Microsoft Visual C++ 2010 SP1 Redistributable Package (x64)

diff --git a/docs/groovy-2.5-clibuilder-renewal-part1.adoc b/docs/groovy-2.5-clibuilder-renewal-part1.adoc
@@ -9,6 +9,9 @@
 :source-highlighter: coderay
 :icons: font
 :imagesdir: images
+ifdef::env-github[]
+:note-caption: :information_source:
+endif::[]
 
 The `CliBuilder` class for quickly and concisely building command line applications has been renewed in Apache Groovy 2.5.
 This two-part article highlights what is new.

diff --git a/docs/groovy-2.5-clibuilder-renewal-part2.adoc b/docs/groovy-2.5-clibuilder-renewal-part2.adoc
@@ -9,6 +9,9 @@
 :source-highlighter: coderay
 :icons: font
 :imagesdir: images
+ifdef::env-github[]
+:note-caption: :information_source:
+endif::[]
 
 The `CliBuilder` class for quickly and concisely building command line applications has been renewed in Apache Groovy 2.5.
 This is the second of a two-part article series that highlights what is new.

diff --git a/docs/index.adoc b/docs/index.adoc
@@ -6,13 +6,20 @@
 :toc: left
 :numbered:
 :toclevels: 2
-:toc-title: Features
+:toc-title: Table of contents
 :source-highlighter: coderay
 //:source-highlighter: highlightjs
 //:highlightjs-theme: darkula
 :icons: font
 :imagesdir: images
 :sectanchors:
+ifdef::env-github[]
+:caution-caption: :fire:
+:important-caption: :heavy_exclamation_mark:
+:note-caption: :information_source:
+:tip-caption: :bulb:
+:warning-caption: :warning:
+endif::[]
 
 [link=https://github.com/remkop/picocli]
 image::https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png[Fork me on GitHub,float="right"]
@@ -28,31 +35,29 @@ image:logo/horizontal.png[picocli the Mighty Tiny Command Line Interface,width=8
 The user manual for the latest release is at http://picocli.info.
 For the busy and impatient: there is also a link:quick-guide.html[Quick Guide].
 
-== Introduction
+== Introducing Picocli
+Picocli is a one-file framework for creating Java command line applications with almost zero code.
 Picocli aims to be the easiest way to create rich command line applications that can run on and off the JVM.
 
-Picocli is a one-file framework for creating Java command line applications with almost zero code.
-Supports a variety of command line syntax styles including POSIX, GNU, MS-DOS and more.
-Generates highly customizable usage help messages with <<ANSI Colors and Styles,ANSI colors and styles>>.
+=== Features
+Picocli supports a variety of command line syntax styles including POSIX, GNU, MS-DOS and more and generates highly customizable usage help messages with <<ANSI Colors and Styles,ANSI colors and styles>>.
 Picocli-based applications can have link:autocomplete.html[command line TAB completion] showing available options, option parameters and subcommands, for any level of nested subcommands.
 Picocli-based applications can be ahead-of-time compiled to a image:https://www.graalvm.org/resources/img/logo-colored.svg[GraalVM]
 <<GraalVM Native Image,native image>>, with extremely fast startup time and lower memory requirements, which can be distributed as a single executable file.
 
-
-image:checksum-usage-help.png[Screenshot of usage help with Ansi codes enabled]
-
 Picocli <<Generate Man Page Documentation,generates beautiful documentation>> for your application (HTML, PDF and Unix man pages).
 
 Another distinguishing feature of picocli is how it aims
 to let users run picocli-based applications without requiring picocli as an external dependency:
 all the source code lives in a single file, to encourage application authors to include it _in source form_.
 
-How it works: annotate your class and picocli initializes it from the command line arguments,
-converting the input to strongly typed values in the fields of your class.
+=== Sample application
+Let's get started by looking at minimal picocli-based command line application. This fully working sample app may be used to calculate the checksum(s) of one or more file(s) given as command line parameter(s):
 
-TIP: picocli also provides a <<Programmatic API,programmatic API>>, separately from the annotations API.
+.Synopsis of sample application
+image:checksum-usage-help.png[Screenshot of usage help with Ansi codes enabled]
 
-.A full working example picocli-based command line application
+.Source code of sample application
 [[CheckSum-application]]
 [source,java]
 ----
@@ -67,25 +72,25 @@ import java.nio.file.Files;
 import java.security.MessageDigest;
 import java.util.concurrent.Callable;
 
-@Command(name = "checksum", mixinStandardHelpOptions = true, version = "checksum 4.0",
+@Command(name = "checksum", mixinStandardHelpOptions = true, version = "checksum 4.0", // <8>
          description = "Prints the checksum (MD5 by default) of a file to STDOUT.")
-class CheckSum implements Callable<Integer> {
+class CheckSum implements Callable<Integer> { // <1>
 
-    @Parameters(index = "0", description = "The file whose checksum to calculate.")
-    private File file;
+    @Parameters(index = "0", description = "The file whose checksum to calculate.") // <2>
+    private File file; // <4>
 
-    @Option(names = {"-a", "--algorithm"}, description = "MD5, SHA-1, SHA-256, ...")
-    private String algorithm = "MD5";
+    @Option(names = {"-a", "--algorithm"}, description = "MD5, SHA-1, SHA-256, ...") // <3>
+    private String algorithm = "MD5"; // <4>
 
     // this example implements Callable, so parsing, error handling and handling user
     // requests for usage help or version help can be done with one line of code.
     public static void main(String... args) {
-        int exitCode = new CommandLine(new CheckSum()).execute(args);
-        System.exit(exitCode);
+        int exitCode = new CommandLine(new CheckSum()).execute(args); // <5>
+        System.exit(exitCode); // <7>
     }
 
     @Override
-    public Integer call() throws Exception { // your business logic goes here...
+    public Integer call() throws Exception { // your business logic // <6>
         byte[] fileContents = Files.readAllBytes(file.toPath());
         byte[] digest = MessageDigest.getInstance(algorithm).digest(fileContents);
         System.out.printf("%0" + (digest.length*2) + "x%n", new BigInteger(1, digest));
@@ -94,15 +99,11 @@ class CheckSum implements Callable<Integer> {
 }
 ----
 
-Implement `Runnable` or `Callable`, and your command can be <<Executing Commands,executed>> in one line of code.
-The example above uses the `CommandLine.execute` method
-to parse the command line, handle errors, handle requests for usage and version help, and invoke the business logic.
-Applications can call `System.exit` with the returned exit code to signal success or failure to their caller.
-
-The <<Mixin Standard Help Options,mixinStandardHelpOptions>> attribute adds `--help` and `--version` options to your application.
+_This is how it works_: Create a class ➊ that represents your command and annotate this class with @Command ➑. Let this class implement `Runnable` or `Callable` and picocli will kick off your application after parsing is successfully completed. Then, annotate the fields or methods of the command class with @Parameters ➋ and/or @Option ➌ to declare what positional parameters and/or options your application expects. Picocli will convert the command line arguments given to your app to strongly typed values in the fields ➍ of your class. In the `main` method of your class, use the `CommandLine.execute` method ➎ to parse the command line, handle errors, handle requests for usage and version help, and invoke the business logic ➏. Once your business logic finished, you may call `System.exit` ➐ to return an exit code to your caller, indicating success or failure of your business logic. Additionally, you may make use of the <<Mixin Standard Help Options,mixinStandardHelpOptions>> attribute ➑  which adds `--help` and `--version` options to your application.
 
+TIP: Picocli also provides a <<Programmatic API,programmatic API>>, separately from the annotations API.
 
-== Getting Started
+== Setting up your picocli based project
 You can add picocli as an external dependency to your project, or you can include it as source.
 
 === Add as External Dependency

diff --git a/docs/picocli-on-graalvm.adoc b/docs/picocli-on-graalvm.adoc
@@ -1,6 +1,9 @@
 = Picocli on GraalVM: Blazingly Fast Command Line Apps
 :source-highlighter: highlightjs
 :highlightjs-theme: darkula
+ifdef::env-github[]
+:tip-caption: :bulb:
+endif::[]
 
 image::https://picocli.info/images/picocli-on-graalvm.png[]
 

diff --git a/docs/picocli-programmatic-api.adoc b/docs/picocli-programmatic-api.adoc
@@ -9,6 +9,10 @@
 :source-highlighter: coderay
 :icons: font
 :imagesdir: images
+ifdef::env-github[]
+:caution-caption: :fire:
+:tip-caption: :bulb:
+endif::[]
 
 TIP: For most applications the annotations API is a better fit than the programmatic API: the annotation syntax is more compact, easier to read, and easier to maintain. See this https://picocli.info/quick-guide.html[quick guide] and for more details, the http://picocli.info[user manual].
 
@@ -38,16 +42,16 @@ When used as a library, the application calls the `CommandLine.parseArgs` method
 public class ProgrammaticCommand {
 
     public static void main(String[] args) {
-        CommandSpec spec = CommandSpec.create();
+        CommandSpec spec = CommandSpec.create(); // <1>
         spec.mixinStandardHelpOptions(true); // usageHelp and versionHelp options
         spec.addOption(OptionSpec.builder("-c", "--count")
                 .paramLabel("COUNT")
                 .type(int.class)
-                .description("number of times to execute").build());
+                .description("number of times to execute").build()); // <2>
         spec.addPositional(PositionalParamSpec.builder()
                 .paramLabel("FILES")
                 .type(List.class).auxiliaryTypes(File.class) // List<File>
-                .description("The files to process").build());
+                .description("The files to process").build()); // <3>
         CommandLine commandLine = new CommandLine(spec);
 
         // set an execution strategy (the run(ParseResult) method) that will be called
@@ -74,16 +78,19 @@ public class ProgrammaticCommand {
     }
 }
 ----
+<1> `CommandSpec`
+<2> `OptionSpec`
+<3> `PositionalParamSpec`
 
 == Configuration
 The following classes are the main model classes used to configure the parser:
 
-* `CommandSpec`
-* `OptionSpec`
-* `PositionalParamSpec`
+* <<CommandSpec,`CommandSpec`>>
+* <<OptionSpec,`OptionSpec`>>
+* <<PositionalParamSpec,`PositionalParamSpec`>>
 
 
-=== `CommandSpec`
+=== CommandSpec
 
 ==== Command Name and Version
 `CommandSpec` models a command. It has a name and a version, both of which may be empty.  For example:
@@ -163,7 +170,7 @@ CommandSpec cmd = CommandSpec.create()
     .addSubcommand("help", helpSubcommand);
 ----
 
-=== `OptionSpec`
+=== OptionSpec
 `OptionSpec` models a command option. An `OptionSpec` must have at least one name, which is used during parsing to match command line arguments. Other attributes can be left empty and picocli will give them a reasonable default value. This defaulting is why `OptionSpec` objects are created with a builder: this allows you to specify only some attributes and let picocli initialise the other attributes. For example, if only the option’s name is specified, picocli assumes the option takes no parameters (arity = 0), and is of type `boolean`. Another example, if arity is larger than `1`, picocli sets the type to `List` and the `auxiliary type` to `String`.
 
 Once an `OptionSpec` is constructed, its configuration becomes immutable, but its `value` can still be modified. Usually the value is set during command line parsing when a command line argument matches one of the option names.
@@ -172,7 +179,7 @@ The value is set via the getter and setter _bindings_. We’ll come back to bind
 
 Similar to the annotation API, `OptionSpec` objects have `help`, `usageHelp` and `versionHelp` attributes. When the parser matches an option that was marked with any of these attributes, it will no longer validate that all required arguments exist. See the section below on the `parseWithHandler(s)` methods that automatically print help when requested.
 
-=== `PositionalParamSpec`
+=== PositionalParamSpec
 
 `PositionalParamSpec` objects don’t have names, but have an index range instead. A single `PositionalParamSpec` object can capture multiple positional parameters. The default index range is set to `0..*` (all indices). A command may have multiple `PositionalParamSpec` objects to capture positional parameters at different index ranges. This can be useful if positional parameters at different index ranges have different data types.
 
@@ -491,4 +498,4 @@ public class MyApp {
 }
 ----
 
-For more detail, see the https://picocli.info/#execute[Executing Commands] section of the user manual.
+For more details, see the https://picocli.info/#execute[Executing Commands] section of the user manual.
diff --git a/docs/quick-guide.adoc b/docs/quick-guide.adoc
@@ -10,6 +10,11 @@
 :source-highlighter: coderay
 :icons: font
 :imagesdir: images
+ifdef::env-github[]
+:caution-caption: :fire:
+:important-caption: :heavy_exclamation_mark:
+:note-caption: :information_source:
+endif::[]
 
 This is the Quick Guide. For more detail, see the full user manual at http://picocli.info[http://picocli.info].
 

diff --git a/picocli-codegen/README.adoc b/picocli-codegen/README.adoc
@@ -8,6 +8,10 @@
 //:source-highlighter: highlightjs
 //:highlightjs-theme: darkula
 :icons: font
+ifdef::env-github[]
+:caution-caption: :fire:
+:tip-caption: :bulb:
+endif::[]
 
 image::https://picocli.info/images/logo/horizontal-400x150.png[picocli,height="150px"]