doc: Improve readme

README.md

@@ -55,96 +55,131 @@ Then add it to your packages:
 }
 ```
 
-## Usage
+## Setup
+
+### As an alias
+
+The quickest way to get started with `sub` is to define an alias for your CLI
+(let's call it `hat`) in your shell:
+
+```sh
+alias hat='sub --name hat --absolute /path/to/cli/root --'
+```
 
-`sub` is meant to be used as the entry point for a CLI. Given the following
-directory structure:
+Where `/path/to/cli/root` contains a `libexec` directory with executable
+scripts, for example:
+
+```
+.
+└── libexec
+    ├── user-script1
+    ├── user-script2
+    └── user-script3
+```
+
+### As an executable
+
+A more reliable way is to use an executable script as the entry point. Given
+the following directory structure:
 
 ```
 .
 ├── bin
-│   └── awesomecli
+│   └── hat
 └── libexec
-    ├── list
-    ├── new
-    ├── open
-    └── nested
-        ├── README
-        └── command
+    ├── user-script1
+    ├── user-script2
+    └── user-script3
 ```
 
-The entry point in `bin/awesomecli` can then be:
+The entry point in `bin/hat` is then:
 
 ```bash
 #!/usr/bin/env bash
 
-sub --name awesomecli --executable "${BASH_SOURCE[0]}" --relative ".." -- "$@"
+sub --name hat --executable "${BASH_SOURCE[0]}" --relative ".." -- "$@"
 ```
 
-The `--name` argument tells `sub` the name of the CLI. This is used when
-printing help information.
-
 The `--executable` argument tells `sub` where the CLI entry point is located.
-Usually this will just be `${BASH_SOURCE[0]}`. The `--relative` argument tells
-`sub` how to find the root of the CLI starting from the CLI entry point.
+This will almost always be `${BASH_SOURCE[0]}`. The `--relative` argument tells
+`sub` how to find the root of the CLI starting from the CLI entry point. In the
+line above, just replace `hat` with the name of your CLI.
 
-After the root directory is determined, `sub` picks up any executable files in
-a `libexec` directory inside root to use as subcommands. Directories create
-nested subcommands. Arguments for the subcommands themselves go after the `--`.
+## Usage
 
-With this setup, invoking `awesomecli` will display all available subcommands
-with associated help information. To invoke a subcommand, use:
+Once you have set up your CLI, you can get help by running:
 
+```sh
+$ hat --help
+```
 ```
-$ awesomecli <subcommandname> <args>
+Usage: hat [OPTIONS] [commands_with_args]...
+
+Arguments:
+  [commands_with_args]...
+
+Options:
+      --usage                  Print usage
+  -h, --help                   Print help
+      --completions            Print completions
+      --commands               Print subcommands
+      --extension <extension>  Filter subcommands by extension
+
+Available subcommands:
+    user-script1
+    user-script2
+    user-script3
 ```
 
-Or to invoke a nested subcommand:
+To invoke a subcommand, use:
 
 ```
-$ awesomecli nested command
+$ hat user-script1
 ```
 
-## Documenting commands
-
 To get help for a command, use the built in `--help` flag:
 
 ```sh
-awesomecli --help <commandname>
+hat --help <commandname>
 ```
 or
 ```sh
-awesomecli <commandname> --help
+hat <commandname> --help
 ```
 
+## Documenting commands
+
 In order to display help information, `sub` looks for special comments in the
-corresponding script. An example documented command:
+corresponding script. A fully documented `hello` script could look like this:
 
 ```sh
 #!/usr/bin/env bash
 #
-# Summary: One line summary of the command
+# Summary: Say hello
 #
-# Usage: {cmd} <positional-arg>
+# Usage: {cmd} <name> [--spanish]
 #
-# Extended description of what the command does.
+# Say hello to a user by name.
 #
-# The extended description can span multiple lines.
+# With the --spanish flag, the greeting will be in Spanish.
 
 set -e
 
-echo "Hello $1"
-```
+declare -A args="($_HAT_ARGS)"
 
-If the command is a directory, `sub` looks for documentation in a `README` file
-inside that directory.
+if [[ "${args[spanish]}" == "true" ]]; then
+  echo "¡Hola, ${args[name]}!"
+else
+  echo "Hello, ${args[name]}!"
+fi
+```
 
 ## Sharing code between scripts
 
 When invoking subcommands, `sub` sets an environment variable called
-`_CLINAME_ROOT` (where `CLINAME` is the name of your CLI. This variable holds
-the canonicalized path to the root of your CLI. It can be used for instance for
-sourcing shared scripts from a `lib` directory next to `libexec`:
+`_HAT_ROOT` (where `HAT` is the capitalized name of your CLI. This variable
+holds the canonicalized path to the root of your CLI. It can be used for
+instance for sourcing shared scripts from a `lib` directory next to `libexec`:
 
 ```sh
 source "$_CLINAME_ROOT/lib/shared.sh"
@@ -153,12 +188,13 @@ source "$_CLINAME_ROOT/lib/shared.sh"
 ## Caching
 
 When invoking subcommands, `sub` sets an environment variable called
-`_CLINAME_CACHE` (where `CLINAME` is the name of your CLI. This variable points
-to an XDG compliant cache directory that can be used for storing temporary files.
+`_HAT_CACHE` (where `HAT` is the capitalized name of your CLI. This variable
+points to an XDG compliant cache directory that can be used for storing
+temporary files.
 
 ## Migrating to Sub 2.x
 
-### --bin was renamed to --executable
+### change --bin was to --executable
 
 The `--bin` argument was renamed to `--executable` to better reflect its purpose.