#121 update autocomplete manual

remkop · Aug 8, 2017 · f8d7ffe · f8d7ffe
1 parent e13c0fb
commit f8d7ffe
Show file tree

Hide file tree

Showing 2 changed files with 29 additions and 19 deletions.
diff --git a/docs/1.0.0-SNAPSHOT/autocomplete.html b/docs/1.0.0-SNAPSHOT/autocomplete.html
@@ -748,11 +748,12 @@ <h3 id="_overview">3.1. Overview</h3>
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash">$ java -cp picocli-1.0.0.jar picocli.AutoComplete com.myproject.MyCommand</code></pre>
+<pre class="CodeRay highlight"><code data-lang="bash">$ java -jar picocli-1.0.0.jar com.myproject.MyCommand</code></pre>
 </div>
 </div>
 <div class="paragraph">
-<p><code>picocli.AutoComplete</code> will instantiate your command, and inspect it for <code>@Option</code> and <code>@Command</code> annotations. Based on these annotations it will  generate a completion script in the current directory.</p>
+<p>This will instantiate your command, and inspect it for <code>@Option</code> and <code>@Command</code> annotations.
+Based on these annotations it will generate a completion script in the current directory.</p>
 </div>
 </div>
 <div class="sect2">
@@ -763,7 +764,7 @@ <h3 id="_command_name">3.2. Command Name</h3>
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash">$ java -cp picocli-1.0.0.jar picocli.AutoComplete -n hierarchy com.myproject.MyCommand</code></pre>
+<pre class="CodeRay highlight"><code data-lang="bash">$ java -jar picocli-1.0.0.jar -n hierarchy com.myproject.MyCommand</code></pre>
 </div>
 </div>
 <div class="paragraph">
@@ -789,7 +790,8 @@ <h3 id="_command_name">3.2. Command Name</h3>
 <div class="sect2">
 <h3 id="_subcommands">3.3. Subcommands</h3>
 <div class="paragraph">
-<p>For commands with subcommands, bear in mind that <code>picocli.AutoComplete</code> needs the full hierarchy of command and subcommands to generate a completion script that also works for the subcommands.</p>
+<p>For commands with subcommands, bear in mind that the class that generates the completion script (<code>picocli.AutoComplete</code>)
+needs the full hierarchy of command and subcommands to generate a completion script that also works for the subcommands.</p>
 </div>
 <div class="paragraph">
 <p>The above will work when subcommands are registered declaratively with annotations like <code>@Command(subcommands = { &#8230;&#8203; })</code>.</p>
@@ -838,9 +840,7 @@ <h3 id="_command_script">3.5. Command Script</h3>
 <div class="content">
 <pre class="CodeRay highlight"><code data-lang="bash">#!/usr/bin/env bash
 
-LIBS=path/to/libs
-CP=&quot;${LIBS}/myApp.jar&quot;
-java -cp &quot;${CP}&quot; 'com.myorg.myproject.MainClass' $@</code></pre>
+java -cp myApp.jar com.myorg.myproject.MainClass $@</code></pre>
 </div>
 </div>
 </div>
@@ -853,7 +853,10 @@ <h2 id="_installing_the_completion_script_in_bash">4. Installing the Completion
 <p>Make sure bash completion is installed.</p>
 </div>
 <div class="paragraph">
-<p>Place the completion script file in <code>/etc/bash_completion.d</code> (or <code>/usr/local/etc/bash_completion.d</code> on a Mac). If <code>bash-completion</code> is installed, placing the completion script in either of these directories should be sufficient. (Source your <code>~/.bash_profile</code> or launch a new terminal to start using this completion script.)</p>
+<p>The generated completion script needs to be <a href="http://tldp.org/HOWTO/Bash-Prompt-HOWTO/x237.html">sourced</a> to install it in your current bash session.</p>
+</div>
+<div class="paragraph">
+<p>To install it more permanently, place the completion script file in <code>/etc/bash_completion.d</code> (or <code>/usr/local/etc/bash_completion.d</code> on a Mac). If <code>bash-completion</code> is installed, placing the completion script in either of these directories should be sufficient. (Source your <code>~/.bash_profile</code> or launch a new terminal to start using this completion script.)</p>
 </div>
 <div class="paragraph">
 <p>Alternatively, make a directory <code>mkdir ~/bash_completion.d</code>, and place the completion script in this directory. Edit your <code>~/.bashrc</code> file and add the following:</p>
@@ -877,7 +880,10 @@ <h2 id="_installing_the_completion_script_in_zsh">5. Installing the Completion S
 <p>Zsh can handle bash completions functions. The latest development version of zsh has a function bashcompinit, that when run will allow zsh to read bash completion specifications and functions. This is documented in the zshcompsys man page. To use it all you need to do is run bashcompinit at any time after compinit. It will define complete and compgen functions corresponding to the bash builtins.</p>
 </div>
 <div class="paragraph">
-<p>Make a directory <code>mkdir ~/bash_completion.d</code>, and place the completion script in this directory. Edit your <code>~/.zshrc</code> file and add the following:</p>
+<p>The generated completion script needs to be <a href="http://tldp.org/HOWTO/Bash-Prompt-HOWTO/x237.html">sourced</a> to install it in your current session.</p>
+</div>
+<div class="paragraph">
+<p>To install it more permanently, make a directory <code>mkdir ~/bash_completion.d</code>, and place the completion script in this directory. Edit your <code>~/.zshrc</code> file and add the following:</p>
 </div>
 <div class="listingblock">
 <div class="content">
@@ -946,7 +952,7 @@ <h2 id="_releases">10. Releases</h2>
 <div id="footer">
 <div id="footer-text">
 Version 1.0.0-BETA1<br>
-Last updated 2017-08-08 21:43:12 +09:00
+Last updated 2017-08-08 22:05:59 +09:00
 </div>
 </div>
 </body>

diff --git a/docs/autocomplete.adoc b/docs/autocomplete.adoc
@@ -140,18 +140,19 @@ the fully qualified class name of the annotated command object.
 
 [source,bash]
 ----
-$ java -cp picocli-1.0.0.jar picocli.AutoComplete com.myproject.MyCommand
+$ java -jar picocli-1.0.0.jar com.myproject.MyCommand
 ----
 
-`picocli.AutoComplete` will instantiate your command, and inspect it for `@Option` and `@Command` annotations. Based on these annotations it will  generate a completion script in the current directory.
+This will instantiate your command, and inspect it for `@Option` and `@Command` annotations.
+Based on these annotations it will generate a completion script in the current directory.
 
 === Command Name
 The name of the generated completion script is based on the `@Command(name ="<COMMAND-NAME>")` annotation, or, if that is missing, the command class name.
 Use the `-n` or `--name` option to control the name of the command that the completion script is for.
 
 [source,bash]
 ----
-$ java -cp picocli-1.0.0.jar picocli.AutoComplete -n hierarchy com.myproject.MyCommand
+$ java -jar picocli-1.0.0.jar -n hierarchy com.myproject.MyCommand
 ----
 
 This will generate a  `hierarchy_completion` script in the current directory.
@@ -163,7 +164,8 @@ Other options are:
 * Use the `-w`, `--writeCommandScript` option to generate a sample command script.
 
 === Subcommands
-For commands with subcommands, bear in mind that `picocli.AutoComplete` needs the full hierarchy of command and subcommands to generate a completion script that also works for the subcommands.
+For commands with subcommands, bear in mind that the class that generates the completion script (`picocli.AutoComplete`)
+needs the full hierarchy of command and subcommands to generate a completion script that also works for the subcommands.
 
 The above will work when subcommands are registered declaratively with annotations like `@Command(subcommands = { ... })`.
 
@@ -193,16 +195,16 @@ It should contain something like this:
 ----
 #!/usr/bin/env bash
 
-LIBS=path/to/libs
-CP="${LIBS}/myApp.jar"
-java -cp "${CP}" 'com.myorg.myproject.MainClass' $@
+java -cp myApp.jar com.myorg.myproject.MainClass $@
 ----
 
 == Installing the Completion Script in Bash
 
 Make sure bash completion is installed.
 
-Place the completion script file in `/etc/bash_completion.d` (or `/usr/local/etc/bash_completion.d` on a Mac). If `bash-completion` is installed, placing the completion script in either of these directories should be sufficient. (Source your `~/.bash_profile` or launch a new terminal to start using this completion script.)
+The generated completion script needs to be http://tldp.org/HOWTO/Bash-Prompt-HOWTO/x237.html[sourced] to install it in your current bash session.
+
+To install it more permanently, place the completion script file in `/etc/bash_completion.d` (or `/usr/local/etc/bash_completion.d` on a Mac). If `bash-completion` is installed, placing the completion script in either of these directories should be sufficient. (Source your `~/.bash_profile` or launch a new terminal to start using this completion script.)
 
 Alternatively, make a directory `mkdir ~/bash_completion.d`, and place the completion script in this directory. Edit your `~/.bashrc` file and add the following:
 
@@ -220,7 +222,9 @@ Source your `~/.bash_profile` or launch a new terminal to start using this compl
 
 Zsh can handle bash completions functions. The latest development version of zsh has a function bashcompinit, that when run will allow zsh to read bash completion specifications and functions. This is documented in the zshcompsys man page. To use it all you need to do is run bashcompinit at any time after compinit. It will define complete and compgen functions corresponding to the bash builtins.
 
-Make a directory `mkdir ~/bash_completion.d`, and place the completion script in this directory. Edit your `~/.zshrc` file and add the following:
+The generated completion script needs to be http://tldp.org/HOWTO/Bash-Prompt-HOWTO/x237.html[sourced] to install it in your current session.
+
+To install it more permanently, make a directory `mkdir ~/bash_completion.d`, and place the completion script in this directory. Edit your `~/.zshrc` file and add the following:
 
 [source,bash]
 ----