From 40bb7e9a8763d5013ed563dde596b6be8075080e Mon Sep 17 00:00:00 2001
From: Remko Popma <remkop@yahoo.com>
Date: Tue, 11 Feb 2020 19:52:54 +0900
Subject: [PATCH] [#299][#459] update examples and picocli-codegen README

---
 picocli-codegen/README.adoc                   | 61 +++++++++++++------
 .../example-gradle-project/build.gradle       | 20 +++++-
 2 files changed, 59 insertions(+), 22 deletions(-)

diff --git a/picocli-codegen/README.adoc b/picocli-codegen/README.adoc
index a84193a5..e79bac39 100644
--- a/picocli-codegen/README.adoc
+++ b/picocli-codegen/README.adoc
@@ -548,13 +548,13 @@ task generateManpageAsciiDoc(type: JavaExec) {
     description = "Generate AsciiDoc manpage"
     classpath(configurations.compile, configurations.annotationProcessor, sourceSets.main.runtimeClasspath)
     main 'picocli.codegen.docgen.manpage.ManPageGenerator'
-    args mainClassName, "--outdir=${project.buildDir}/generated/docs", "-v" //, "--template-dir=src/docs/mantemplates"
+    args mainClassName, "--outdir=${project.buildDir}/generated-picocli-docs", "-v" //, "--template-dir=src/docs/mantemplates"
 }
 
 apply plugin: 'org.asciidoctor.convert'
 asciidoctor {
     dependsOn(generateManpageAsciiDoc)
-    sourceDir = file("${project.buildDir}/generated/docs")
+    sourceDir = file("${project.buildDir}/generated-picocli-docs")
     outputDir = file("${project.buildDir}/docs")
     logDocuments = true
     backends 'manpage', 'html5'
@@ -562,25 +562,11 @@ asciidoctor {
 ----
 
 
-The `generateManpageAsciiDoc` task generates `<cmd>.adoc` files with doctype `manpage` in `build/generated/docs` for each command and subcommand.
+The `generateManpageAsciiDoc` task generates `<cmd>.adoc` files with doctype `manpage` in `build/generated-picocli-docs` for each command and subcommand.
 
-The `asciidoctor` task converts the generated `<cmd>.adoc` files in `build/generated/docs` to `<cmd>.1` manpage files in `build/docs/manpage/`, and to `<cmd>.html` HTML files in `build/docs/html5/`.
+The `asciidoctor` task converts the generated `<cmd>.adoc` files in `build/generated-picocli-docs` to `<cmd>.1` manpage files in `build/docs/manpage/`, and to `<cmd>.html` HTML files in `build/docs/html5/`.
 
-You could then use the Gradle `distribution` plugin to include the generated manpage files in the distribution archive:
-
-[source,groovy]
-----
-apply plugin: "distribution"
-distributions {
-    main {
-        contents {
-            from ("${project.buildDir}/docs/manpage") {
-                into('docs')
-            }
-        }
-    }
-}
-----
+See the link:https://github.com/remkop/picocli/tree/master/picocli-examples/generate-man-pages/example-gradle-project[example-gradle-project] in the `picocli-examples` module for a full working example.
 
 
 === Maven Example
@@ -614,7 +600,7 @@ Note that the `picocli-codegen` module is only added as a dependency for the `ex
         <includePluginDependencies>true</includePluginDependencies>
         <mainClass>picocli.codegen.docgen.manpage.ManPageGenerator</mainClass>
         <arguments>
-          <argument>--outdir=target/generated/docs</argument>
+          <argument>--outdir=${project.build.directory}/generated-picocli-docs</argument>
           <argument>com.your.package.YourCommand1</argument>
           <argument>com.your.package.YourCommand2</argument>
         </arguments>
@@ -628,10 +614,45 @@ Note that the `picocli-codegen` module is only added as a dependency for the `ex
         </dependency>
       </dependencies>
     </plugin>
+
+    <plugin>
+      <groupId>org.asciidoctor</groupId>
+      <artifactId>asciidoctor-maven-plugin</artifactId>
+      <version>1.6.0</version>
+      <executions>
+        <execution>
+          <id>output-html</id>
+          <phase>process-classes</phase>
+          <goals>
+            <goal>process-asciidoc</goal>
+          </goals>
+          <configuration>
+            <sourceHighlighter>coderay</sourceHighlighter>
+            <backend>html5</backend>
+          </configuration>
+        </execution>
+        <execution>
+          <id>output-manpage</id>
+          <phase>process-classes</phase>
+          <goals>
+            <goal>process-asciidoc</goal>
+          </goals>
+          <configuration>
+            <sourceHighlighter>coderay</sourceHighlighter>
+            <backend>manpage</backend>
+          </configuration>
+        </execution>
+      </executions>
+      <configuration>
+        <sourceDirectory>${project.build.directory}/generated-picocli-docs</sourceDirectory>
+      </configuration>
+    </plugin>
   </plugins>
 </build>
 ----
 
+See the link:https://github.com/remkop/picocli/tree/master/picocli-examples/generate-man-pages/example-maven-project[example-maven-project] in the `picocli-examples` module for a full working example.
+
 === Customizing with Templates
 The generated man page is very similar to the online help generated by the command itself when a user specifies the `--help` option.
 You may want to add more details or extra sections to the man page.
diff --git a/picocli-examples/generate-man-pages/example-gradle-project/build.gradle b/picocli-examples/generate-man-pages/example-gradle-project/build.gradle
index b6a81ac3..93dff826 100644
--- a/picocli-examples/generate-man-pages/example-gradle-project/build.gradle
+++ b/picocli-examples/generate-man-pages/example-gradle-project/build.gradle
@@ -47,15 +47,31 @@ task generateManpageAsciiDoc(type: JavaExec) {
     description = "Generate AsciiDoc manpage"
     classpath(configurations.compile, configurations.annotationProcessor, sourceSets.main.runtimeClasspath)
     main 'picocli.codegen.docgen.manpage.ManPageGenerator'
-    args project.ext.mainClassName, "--outdir=${project.buildDir}/generated/docs", "-v", "--template-dir=src/docs/mantemplates"
+    args project.ext.mainClassName, "--outdir=${project.buildDir}/generated-picocli-docs", "-v", "--template-dir=src/docs/mantemplates"
 }
 
 apply plugin: 'org.asciidoctor.convert'
 asciidoctor {
     dependsOn(generateManpageAsciiDoc)
-    sourceDir = file("${project.buildDir}/generated/docs")
+    sourceDir = file("${project.buildDir}/generated-picocli-docs")
     outputDir = file("${project.buildDir}/docs")
     logDocuments = true
     backends 'manpage', 'html5'
 }
 assemble.dependsOn(asciidoctor)
+
+// We can now use the Gradle `distribution` plugin to include
+// the generated manpage files in the distribution archive:
+apply plugin: "distribution"
+distributions {
+    main {
+        contents {
+            from ("${project.buildDir}/docs/manpage") {
+                into('man')
+            }
+            from ("${project.buildDir}/docs/html5") {
+                into('docs')
+            }
+        }
+    }
+}