docs: improve docs site

Signed-off-by: Christian Stewart <christian@aperture.us>

Author: paralin

docs/examples/arguments.md

@@ -3,7 +3,7 @@ search:
   boost: 2
 ---
 
-You can lookup arguments by calling the `Args` function on `cli.Context`, e.g.:
+Accessing command-line arguments (values passed after the command and flags) is straightforward using the `Args` method on `cli.Context`. Here's an example:
 
 <!-- {
   "output": "Hello \""

docs/examples/bash-completions.md

@@ -3,10 +3,7 @@ search:
   boost: 2
 ---
 
-You can enable completion commands by setting the `EnableBashCompletion` flag on
-the `App` object to `true`.  By default, this setting will allow auto-completion
-for an app's subcommands, but you can write your own completion methods for the
-App or its subcommands as well.
+You can enable built-in bash completion support by setting the `EnableBashCompletion` field on your `cli.App` to `true`. This automatically provides completion suggestions for your app's subcommands. You can also define custom completion logic for specific commands or flags.
 
 #### Default auto-completion
 
@@ -128,16 +125,13 @@ func main() {
 
 #### Enabling
 
-To enable auto-completion for the current shell session, a bash script,
-`autocomplete/bash_autocomplete` is included in this repo.
+To enable auto-completion for your application in the current shell session, you can use the `autocomplete/bash_autocomplete` script provided in the `aperturerobotics/cli` repository.
 
 > :warning: The `bash-completion` package or equivalent that provides the
 > `_get_comp_words_by_ref` function for the target platform must be installed and
 > initialized for this completion script to work correctly.
 
-To use `autocomplete/bash_autocomplete` set an environment variable named `PROG`
-to the name of your program and then `source` the
-`autocomplete/bash_autocomplete` file.
+First, set the `PROG` environment variable to the name of your compiled application binary. Then, `source` the `autocomplete/bash_autocomplete` script:
 
 For example, if your cli program is called `myprogram`:
 
@@ -150,19 +144,16 @@ a new shell.
 
 #### Distribution and Persistent Autocompletion
 
-Copy `autocomplete/bash_autocomplete` into `/etc/bash_completion.d/` and rename
-it to the name of the program you wish to add autocomplete support for (or
-automatically install it there if you are distributing a package). Don't forget
-to source the file or restart your shell to activate the auto-completion.
+To make autocompletion persistent across shell sessions, you have a few options:
+
+1.  **System-wide Installation:** Copy `autocomplete/bash_autocomplete` to `/etc/bash_completion.d/` and rename it to match your program's name (e.g., `/etc/bash_completion.d/myprogram`). This is common when distributing packages. Users may need to restart their shell or source the file manually (`source /etc/bash_completion.d/<myprogram>`) for the changes to take effect immediately.
 
 ```sh-session
 $ sudo cp path/to/autocomplete/bash_autocomplete /etc/bash_completion.d/<myprogram>
 $ source /etc/bash_completion.d/<myprogram>
 ```
 
-Alternatively, you can just document that users should `source` the generic
-`autocomplete/bash_autocomplete` and set `$PROG` within their bash configuration
-file, adding these lines:
+2.  **User Configuration:** Instruct users to add the following lines to their shell configuration file (e.g., `~/.bashrc` or `~/.bash_profile`), ensuring they replace `<myprogram>` with the actual program name and `path/to/cli` with the correct path to the script:
 
 ```sh-session
 $ PROG=<myprogram>

docs/examples/combining-short-options.md

@@ -3,16 +3,15 @@ search:
   boost: 2
 ---
 
-Traditional use of options using their shortnames look like this:
+Normally, short options (like `-s`, `-o`, `-m`) are specified individually:
 
 ```sh-session
 $ cmd -s -o -m "Some message"
 ```
 
-Suppose you want users to be able to combine options with their shortnames. This
-can be done using the `UseShortOptionHandling` bool in your app configuration,
-or for individual commands by attaching it to the command configuration. For
-example:
+If you want to allow users to combine multiple short boolean options (and optionally one non-boolean short option at the end), you can enable this behavior by setting `UseShortOptionHandling` to `true` on your `cli.App` or a specific `cli.Command`.
+
+Here's an example:
 
 <!-- {
   "args": ["short", "&#45;som", "Some message"],
@@ -66,7 +65,4 @@ following syntax:
 $ cmd -som "Some message"
 ```
 
-If you enable `UseShortOptionHandling`, then you must not use any flags that
-have a single leading `-` or this will result in failures. For example,
-`-option` can no longer be used. Flags with two leading dashes (such as
-`--options`) are still valid.
+**Important:** When `UseShortOptionHandling` is enabled, you cannot define flags that use a single dash followed by multiple characters (e.g., `-option`). This syntax becomes ambiguous with combined short options. Standard double-dash flags (e.g., `--option`) remain unaffected.

docs/examples/exit-codes.md

@@ -3,10 +3,9 @@ search:
   boost: 2
 ---
 
-Calling `App.Run` will not automatically call `os.Exit`, which means that by
-default the exit code will "fall through" to being `0`.  An explicit exit code
-may be set by returning a non-nil error that fulfills `cli.ExitCoder`, *or* a
-`cli.MultiError` that includes an error that fulfills `cli.ExitCoder`, e.g.:
+By default, `App.Run` does not call `os.Exit`. If your application's `Action` (or subcommand actions) returns `nil`, the process exits with code `0`. To exit with a specific non-zero code, return an error that implements the `cli.ExitCoder` interface. The `cli.Exit` helper function is provided for convenience. If using `cli.MultiError`, the exit code will be determined by the first `cli.ExitCoder` found within the wrapped errors.
+
+Here's an example using `cli.Exit`:
 <!-- {
   "error": "Ginger croutons are not in the soup"
 } -->

docs/examples/flags.md

@@ -3,7 +3,7 @@ search:
   boost: 2
 ---
 
-Setting and querying flags is simple.
+Flags provide ways for users to modify the behavior of your command-line application. Defining and accessing flags is straightforward.
 
 <!-- {
   "output": "Hello Nefertiti"
@@ -48,9 +48,7 @@ func main() {
 }
 ```
 
-You can also set a destination variable for a flag, to which the content will be
-scanned. Note that if the `Value` is set for the flag, it will be shown as default,
-and destination will be set to this value before parsing flag on the command line.
+You can also bind a flag directly to a variable in your code using the `Destination` field. The flag's value will be automatically parsed and stored in the specified variable. If a default `Value` is also set for the flag, the `Destination` variable will be initialized to this default before command-line arguments are parsed.
 
 <!-- {
   "output": "Hello someone"
@@ -98,11 +96,11 @@ func main() {
 }
 ```
 
-See full list of flags at https://pkg.go.dev/github.com/aperturerobotics/cli
+See the [Go Reference](https://pkg.go.dev/github.com/aperturerobotics/cli) for a full list of available flag types.
 
-For bool flags you can specify the flag multiple times to get a count(e.g -v -v -v or -vvv)
+For boolean flags (`BoolFlag`), you can use the `Count` field to track how many times a flag is provided. This is useful for flags like `-v` for verbosity.
 
-> If you want to support the `-vvv` flag, you need to set `App.UseShortOptionHandling`.
+> Note: To support combining short boolean flags like `-vvv`, you must set `UseShortOptionHandling: true` on your `App` or `Command`. See the [Combining Short Options](./combining-short-options/) example for details.
 
 <!-- {
   "args": ["&#45;&#45;f", "&#45;&#45;f", "&#45;fff",  "&#45;f"],
@@ -146,8 +144,7 @@ func main() {
 
 #### Placeholder Values
 
-Sometimes it's useful to specify a flag's value within the usage string itself.
-Such placeholders are indicated with back quotes.
+You can indicate a placeholder for a flag's value directly within the `Usage` string. This helps clarify what kind of value the flag expects in the help output. Placeholders are denoted using backticks (` `` `).
 
 For example this:
 
@@ -193,8 +190,7 @@ be left as-is.
 
 #### Alternate Names
 
-You can set alternate (or short) names for flags by providing a comma-delimited
-list for the `Name`. e.g.
+Flags can have multiple names, often a longer descriptive name and a shorter alias. You can define aliases using the `Aliases` field, which accepts a slice of strings.
 
 <!-- {
   "args": ["&#45;&#45;help"],
@@ -214,8 +210,8 @@ func main() {
 	app := &cli.App{
 		Flags: []cli.Flag{
 			&cli.StringFlag{
-				Name:    "lang",
-				Aliases: []string{"l"},
+				Name:    "lang",        // Primary name
+				Aliases: []string{"l"}, // Alternate names
 				Value:   "english",
 				Usage:   "language for the greeting",
 			},
@@ -228,13 +224,11 @@ func main() {
 }
 ```
 
-That flag can then be set with `--lang spanish` or `-l spanish`. Note that
-giving two different forms of the same flag in the same command invocation is an
-error.
+That flag can then be set with `--lang spanish` or `-l spanish`. Providing both forms (e.g., `--lang spanish -l spanish`) in the same command invocation will result in an error.
 
 #### Multiple Values per Single Flag
 
-Using a slice flag allows you to pass multiple values for a single flag; the values will be provided as a slice:
+Slice flags allow users to specify a flag multiple times, collecting all provided values into a slice. Available types include:
 
 - `Int64SliceFlag`
 - `IntSliceFlag`
@@ -274,7 +268,7 @@ func main() {
 }
 ```
 
-Multiple values need to be passed as separate, repeating flags, e.g. `--greeting Hello --greeting Hola`.
+To pass multiple values, the user repeats the flag, e.g., `--greeting Hello --greeting Hola`.
 
 #### Grouping
 
@@ -403,7 +397,7 @@ Will result in help output like:
 
 #### Values from the Environment
 
-You can also have the default value set from the environment via `EnvVars`.  e.g.
+You can specify environment variables that can provide default values for flags using the `EnvVars` field (a slice of strings).
 
 <!-- {
   "args": ["&#45;&#45;help"],
@@ -438,8 +432,7 @@ func main() {
 }
 ```
 
-If `EnvVars` contains more than one string, the first environment variable that
-resolves is used.
+If `EnvVars` contains multiple variable names, the library uses the value of the first environment variable found to be set.
 
 <!-- {
   "args": ["&#45;&#45;help"],
@@ -474,11 +467,11 @@ func main() {
 }
 ```
 
-When `Value` is not set for the flag, but a matching environment variable is found, the value from the environment will be used in the generated docs as the default value.
+If a flag's `Value` field is not explicitly set, but a corresponding environment variable from `EnvVars` is found, the environment variable's value will be used as the default and shown in the help text.
 
-#### Values from files
+#### Values from Files
 
-You can also have the default value set from file via `FilePath`.  e.g.
+Similarly to environment variables, you can specify a file path from which to read a flag's default value using the `FilePath` field.
 
 <!-- {
   "args": ["&#45;&#45;help"],
@@ -512,13 +505,11 @@ func main() {
 }
 ```
 
-Note that default values set from the environment (e.g. `EnvVar`) take precedence over
-default values set from file (e.g. `FilePath`).
+Note that default values sourced from environment variables (`EnvVars`) take precedence over those sourced from files (`FilePath`). See the full precedence order below.
 
 #### Required Flags
 
-You can make a flag required by setting the `Required` field to `true`. If a user
-does not provide a required flag, they will be shown an error message.
+You can enforce that a flag must be provided by the user by setting its `Required` field to `true`. If a required flag is missing, the application will print an error message and exit.
 
 Take for example this app that requires the `lang` flag:
 
@@ -568,11 +559,9 @@ If the app is run without the `lang` flag, the user will see the following messa
 Required flag "lang" not set
 ```
 
-#### Default Values for help output
+#### Default Values for Help Output
 
-Sometimes it's useful to specify a flag's default help-text value within the
-flag declaration. This can be useful if the default value for a flag is a
-computed value. The default value can be set via the `DefaultText` struct field.
+In cases where a flag's default value (`Value` field) is dynamic or complex to represent (e.g., a randomly generated port), you can specify custom text to display as the default in the help output using the `DefaultText` field. This text is purely for display purposes and doesn't affect the actual default value used by the application.
 
 For example this:
 
@@ -616,17 +605,16 @@ Will result in help output like:
 
 #### Precedence
 
-The precedence for flag value sources is as follows (highest to lowest):
+The order of precedence for determining a flag's value is as follows (from highest to lowest):
 
-0. Command line flag value from user
-0. Environment variable (if specified)
-0. Configuration file (if specified)
-0. Default defined on the flag
+1.  Value provided on the command line by the user.
+2.  Value from the first set environment variable listed in `EnvVars`.
+3.  Value read from the file specified in `FilePath`.
+4.  Default value specified in the `Value` field of the flag definition.
 
 #### Flag Actions
 
-Handlers can be registered per flag which are triggered after a flag has been processed. 
-This can be used for a variety of purposes, one of which is flag validation
+You can attach an `Action` function directly to a flag definition. This function will be executed *after* the flag's value has been parsed from the command line, environment, or file. This is useful for performing validation or other logic specific to that flag. The action receives the `*cli.Context` and the parsed value of the flag.
 
 <!-- {
   "args": ["&#45;&#45;port","70000"],

docs/examples/generated-help-text.md

@@ -3,17 +3,16 @@ search:
   boost: 2
 ---
 
-The default help flag (`-h/--help`) is defined as `cli.HelpFlag` and is checked
-by the cli internals in order to print generated help text for the app, command,
-or subcommand, and break execution.
+The library automatically generates help text for your application, commands, and subcommands. By default, this help text is displayed when the user provides the `-h` or `--help` flag (defined by `cli.HelpFlag`). When this flag is detected, the help text is printed, and the application exits.
 
 #### Customization
 
-All of the help text generation may be customized, and at multiple levels.  The
-templates are exposed as variables `AppHelpTemplate`, `CommandHelpTemplate`, and
-`SubcommandHelpTemplate` which may be reassigned or augmented, and full override
-is possible by assigning a compatible func to the `cli.HelpPrinter` variable,
-e.g.:
+You have several ways to customize the generated help output:
+
+1.  **Modify Templates:** The default Go text templates used for generation (`cli.AppHelpTemplate`, `cli.CommandHelpTemplate`, `cli.SubcommandHelpTemplate`) are exported variables. You can modify them directly, for example, by appending extra information or completely replacing them with your own template strings.
+2.  **Replace Help Printer:** For complete control over rendering, you can replace the `cli.HelpPrinter` function. This function receives the output writer, the template string, and the data object (like `*cli.App` or `*cli.Command`) and is responsible for executing the template or generating help in any way you choose.
+
+Here are examples of these customization techniques:
 
 <!-- {
   "output": "Ha HA.  I pwnd the help!!1"
@@ -70,8 +69,7 @@ VERSION:
 }
 ```
 
-The default flag may be customized to something other than `-h/--help` by
-setting `cli.HelpFlag`, e.g.:
+You can also change the flag used to trigger the help display (instead of the default `-h/--help`) by assigning a different `cli.Flag` implementation to the `cli.HelpFlag` variable:
 
 <!-- {
   "args": ["&#45;&#45halp"],

docs/examples/greet.md

@@ -3,9 +3,7 @@ search:
   boost: 2
 ---
 
-Being a programmer can be a lonely job. Thankfully by the power of automation
-that is not the case! Let's create a greeter app to fend off our demons of
-loneliness!
+Let's build a simple "greeter" application to demonstrate the basic structure of a `cli` app. This example will create a command that prints a friendly greeting.
 
 Start by creating a directory named `greet`, and within it, add a file,
 `greet.go` with the following code in it:

docs/examples/subcommands-categories.md

@@ -3,9 +3,7 @@ search:
   boost: 2
 ---
 
-For additional organization in apps that have many subcommands, you can
-associate a category for each command to group them together in the help
-output, e.g.:
+When your application has numerous subcommands, organizing them into categories can significantly improve the clarity of the help output. You can assign a category to a command by setting its `Category` field. Commands with the same category will be grouped together in the help text.
 
 <!-- {
   "output": ".*COMMANDS:\\n.*noop[ ]*\\n.*\\n[ ]*template:\\n[ ]*add[ ]*\\n[ ]*remove.*"

docs/examples/subcommands.md

@@ -3,7 +3,7 @@ search:
   boost: 2
 ---
 
-Subcommands can be defined for a more git-like command line app.
+You can structure your application with subcommands, similar to tools like `git` or `docker`. Define subcommands by assigning a slice of `*cli.Command` structs to the `Commands` field of your `cli.App` or another `cli.Command`.
 
 <!-- {
   "args": ["template", "add"],

docs/examples/suggestions.md

@@ -3,7 +3,4 @@ search:
   boost: 2
 ---
 
-To enable flag and command suggestions, set `app.Suggest = true`. If the suggest
-feature is enabled, then the help output of the corresponding command will
-provide an appropriate suggestion for the provided flag or subcommand if
-available.
+You can enable suggestions for mistyped flags or commands by setting `Suggest: true` on your `cli.App`. When enabled, if a user enters an unrecognized flag or command, the application will suggest the closest match if one is found based on Levenshtein distance.