Starting to give the documentation a very thorough review

Author: tleonhardt

docs/features/argument_processing.md

@@ -4,15 +4,20 @@
 [argparse](https://docs.python.org/3/library/argparse.html) python module. `cmd2` handles the
 following for you:
 
-1. Parsing input and quoted strings like the Unix shell
-1. Parse the resulting argument list using an instance of `argparse.ArgumentParser` that you provide
-1. Passes the resulting `argparse.Namespace` object to your command function. The `Namespace`
-   includes the `Statement` object that was created when parsing the command line. It can be
-   retrieved by calling `cmd2_statement.get()` on the `Namespace`.
+1. Parsing input and quoted strings in a manner similar to how POSIX shells do it
+1. Parse the resulting argument list using an instance of
+   [argparse.ArgumentParser](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser)
+   that you provide
+1. Passes the resulting
+   [argparse.Namespace](https://docs.python.org/3/library/argparse.html#argparse.Namespace) object
+   to your command function. The `Namespace` includes the [Statement][cmd2.Statement] object that
+   was created when parsing the command line. It can be retrieved by calling `cmd2_statement.get()`
+   on the `Namespace`.
 1. Adds the usage message from the argument parser to your command's help.
 1. Checks if the `-h/--help` option is present, and if so, displays the help message for the command
 
-These features are all provided by the `@with_argparser` decorator which is imported from `cmd2`.
+These features are all provided by the [@with_argparser][cmd2.with_argparser] decorator which is
+imported from `cmd2`.
 
 See the
 [argparse_example](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_example.py)
@@ -31,11 +36,11 @@ command which might have its own argument parsing.
 
 ## Argument Parsing
 
-For each command in the `cmd2` subclass which requires argument parsing, create a unique instance of
-`argparse.ArgumentParser()` which can parse the input appropriately for the command. Then decorate
-the command method with the `@with_argparser` decorator, passing the argument parser as the first
-parameter to the decorator. This changes the second argument to the command method, which will
-contain the results of `ArgumentParser.parse_args()`.
+For each command in the `cmd2.Cmd` subclass which requires argument parsing, create a unique
+instance of `argparse.ArgumentParser()` which can parse the input appropriately for the command.
+Then decorate the command method with the `@with_argparser` decorator, passing the argument parser
+as the first parameter to the decorator. This changes the second argument to the command method,
+which will contain the results of `ArgumentParser.parse_args()`.
 
 Here's what it looks like:
 
@@ -65,8 +70,8 @@ def do_speak(self, opts):
 
     `cmd2` sets the `prog` variable in the argument parser based on the name of the method it is decorating. This will override anything you specify in `prog` variable when creating the argument parser.
 
-As of the 3.0.0 release, `cmd2` sets `prog` when the instance-specific parser is created, which is
-later than it did previously.
+    As of the 3.0.0 release, `cmd2` sets `prog` when the instance-specific parser is created, which is
+    later than it did previously.
 
 ## Help Messages
 
@@ -84,7 +89,7 @@ argparser.add_argument('tag', help='tag')
 argparser.add_argument('content', nargs='+', help='content to surround with tag')
 @with_argparser(argparser)
 def do_tag(self, args):
-    """create a html tag"""
+    """Create an HTML tag"""
     self.stdout.write('<{0}>{1}</{0}>'.format(args.tag, ' '.join(args.content)))
     self.stdout.write('\n')
 ```
@@ -94,7 +99,7 @@ the `help tag` command displays:
 ```text
 usage: tag [-h] tag content [content ...]
 
-create an HTML tag
+Create an HTML tag
 
 positional arguments:
   tag         tag
@@ -168,13 +173,13 @@ This command cannot generate tags with no content, like <br/>
 
 !!! warning
 
-    If a command **foo** is decorated with one of cmd2's argparse decorators, then **help_foo** will not be invoked when `help foo` is called. The [argparse](https://docs.python.org/3/library/argparse.html) module provides a rich API which can be used to tweak every aspect of the displayed help and we encourage `cmd2` developers to utilize that.
+    If a command **foo** is decorated with `cmd2`'s `with_argparse` decorator, then **help_foo** will not be invoked when `help foo` is called. The [argparse](https://docs.python.org/3/library/argparse.html) module provides a rich API which can be used to tweak every aspect of the displayed help and we encourage `cmd2` developers to utilize that.
 
 ## Argument List
 
 The default behavior of `cmd2` is to pass the user input directly to your `do_*` methods as a
-string. The object passed to your method is actually a `Statement` object, which has additional
-attributes that may be helpful, including `arg_list` and `argv`:
+string. The object passed to your method is actually a [Statement][cmd2.Statement] object, which has
+additional attributes that may be helpful, including `arg_list` and `argv`:
 
 ```py
 class CmdLineApp(cmd2.Cmd):
@@ -200,8 +205,8 @@ class CmdLineApp(cmd2.Cmd):
 
 If you don't want to access the additional attributes on the string passed to your `do_*` method you
 can still have `cmd2` apply shell parsing rules to the user input and pass you a list of arguments
-instead of a string. Apply the `@with_argument_list` decorator to those methods that should receive
-an argument list instead of a string:
+instead of a string. Apply the [@with_argument_list][cmd2.with_argument_list] decorator to those
+methods that should receive an argument list instead of a string:
 
 ```py
 from cmd2 import with_argument_list
@@ -272,7 +277,7 @@ def settings_ns_provider(self) -> argparse.Namespace:
     return ns
 ```
 
-To use this function with the argparse decorators, do the following:
+To use this function with the `@2ith_argparser` decorator, do the following:
 
 ```py
 @with_argparser(my_parser, ns_provider=settings_ns_provider)
@@ -293,14 +298,16 @@ See the
 [argparse_example](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_example.py)
 example to learn more about how to use subcommands in your `cmd2` application.
 
+The [@as_subcommand_to][cmd2.as_subcommand_to] decorator makes adding subcommands easy.
+
 ## Argparse Extensions
 
 `cmd2` augments the standard `argparse.nargs` with range tuple capability:
 
 - `nargs=(5,)` - accept 5 or more items
 - `nargs=(8, 12)` - accept 8 to 12 items
 
-`cmd2` also provides the `cmd2.argparse_custom.Cmd2ArgumentParser` class which inherits from
+`cmd2` also provides the [Cmd2ArgumentParser][cmd2.Cmd2ArgumentParser] class which inherits from
 `argparse.ArgumentParser` and improves error and help output.
 
 ## Decorator Order
@@ -338,8 +345,8 @@ example demonstrates both above cases in a concrete fashion.
 
 ## Reserved Argument Names
 
-`cmd2` argparse decorators add the following attributes to argparse Namespaces. To avoid naming
-collisions, do not use any of the names for your argparse arguments.
+`cmd2`'s `@with_argparser` decorator adds the following attributes to argparse Namespaces. To avoid
+naming collisions, do not use any of the names for your argparse arguments.
 
 - `cmd2_statement` - `cmd2.Cmd2AttributeWrapper` object containing the `cmd2.Statement` object that
   was created when parsing the command line.

docs/features/builtin_commands.md

@@ -1,6 +1,6 @@
 # Builtin Commands
 
-Applications which subclass `cmd2.Cmd` inherit a number of commands which may be useful to your
+Applications which subclass [cmd2.Cmd][] inherit a number of commands which may be useful to your
 users. Developers can [Remove Builtin Commands](#remove-builtin-commands) if they do not want them
 to be part of the application.
 
@@ -33,7 +33,7 @@ for more information.
 This command allows you to view, run, edit, save, or clear previously entered commands from the
 history. See [History](history.md) for more information.
 
-### ipy
+### ipy (optional)
 
 This optional opt-in command enters an interactive IPython shell. See
 [IPython (optional)](./embedded_python_shells.md#ipython-optional) for more information.
@@ -44,9 +44,9 @@ This command manages macros via subcommands `create`, `delete`, and `list`. A ma
 alias, but it can contain argument placeholders. See [Macros](./shortcuts_aliases_macros.md#macros)
 for more information.
 
-### py
+### py (optional)
 
-This command invokes a Python command or shell. See
+This optional opt-in command invokes a Python command or shell. See
 [Embedded Python Shells](./embedded_python_shells.md) for more information.
 
 ### quit
@@ -63,7 +63,7 @@ This command runs a Python script file inside the `cmd2` application. See
 This command runs commands in a script file that is encoded as either ASCII or UTF-8 text. See
 [Command Scripts](./scripting.md#command-scripts) for more information.
 
-### \_relative_run_script
+### \_relative_run_script (hidden)
 
 This command is hidden from the help that's visible to end users. It runs a script like
 [run_script](#run_script) but does so using a path relative to the script that is currently
@@ -77,21 +77,19 @@ application:
 
 ```text
 (Cmd) set
-Name                    Value                           Description
-====================================================================================================================
-allow_style             Terminal                        Allow ANSI text style sequences in output (valid values:
-                                                        Always, Never, Terminal)
-always_show_hint        False                           Display tab completion hint even when completion suggestions
-                                                        print
-debug                   True                            Show full traceback on exception
-echo                    False                           Echo command issued into output
-editor                  vi                              Program used by 'edit'
-feedback_to_output      False                           Include nonessentials in '|' and '>' results
-max_completion_items    50                              Maximum number of CompletionItems to display during tab
-                                                        completion
-quiet                   False                           Don't print non-essential feedback
-scripts_add_to_history  True                            Scripts and pyscripts add commands to history
-timing                  False                           Report execution times
+ Name                     Value      Description
+───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ allow_style              Terminal   Allow ANSI text style sequences in output (valid values: Always, Never, Terminal)
+ always_show_hint         False      Display tab completion hint even when completion suggestions print
+ debug                    False      Show full traceback on exception
+ echo                     False      Echo command issued into output
+ editor                   vim        Program used by 'edit'
+ feedback_to_output       False      Include nonessentials in '|' and '>' results
+ foreground_color         cyan       Foreground color to use with echo command
+ max_completion_items     50         Maximum number of CompletionItems to display during tab completion
+ quiet                    False      Don't print nonessential feedback
+ scripts_add_to_history   True       Scripts and pyscripts add commands to history
+ timing                   False      Report execution times
 ```
 
 Any of these user-settable parameters can be set while running your app with the `set` command like
@@ -119,10 +117,10 @@ more information.
 
 ## Remove Builtin Commands
 
-Developers may not want to offer the commands builtin to [cmd2.Cmd][] to users of their application.
-To remove a command you must delete the method implementing that command from the [cmd2.Cmd][]
-object at runtime. For example, if you wanted to remove the [shell](#shell) command from your
-application:
+Developers may not want to offer all the commands built into [cmd2.Cmd][] to users of their
+application. To remove a command you must delete the method implementing that command from the
+[cmd2.Cmd][] object at runtime. For example, if you wanted to remove the [shell](#shell) command
+from your application:
 
 ```py
 class NoShellApp(cmd2.Cmd):

docs/features/clipboard.md

@@ -1,8 +1,8 @@
 # Clipboard Integration
 
 Nearly every operating system has some notion of a short-term storage area which can be accessed by
-any program. Usually this is called the clipboard, but sometimes people refer to it as the paste
-buffer.
+any program. Usually this is called the :clipboard: clipboard, but sometimes people refer to it as
+the paste buffer.
 
 `cmd2` integrates with the operating system clipboard using the
 [pyperclip](https://github.com/asweigart/pyperclip) module. Command output can be sent to the
@@ -32,10 +32,4 @@ If you would like your `cmd2` based application to be able to use the clipboard
 alternative ways, you can use the following methods (which work uniformly on Windows, macOS, and
 Linux).
 
-<!-- prettier-ignore-start -->
 ::: cmd2.clipboard
-handler: python
-options:
-show_root_heading: false
-show_source: false
-<!-- prettier-ignore-end -->

docs/features/commands.md

@@ -28,16 +28,16 @@ if __name__ == '__main__':
     sys.exit(c.cmdloop())
 ```
 
-This application subclasses `cmd2.Cmd` but has no code of its own, so all functionality (and there's
-quite a bit) is inherited. Let's create a simple command in this application called `echo` which
-outputs any arguments given to it. Add this method to the class:
+This application subclasses [cmd2.Cmd][] but has no code of its own, so all functionality (and
+there's quite a bit) is inherited. Let's create a simple command in this application called `echo`
+which outputs any arguments given to it. Add this method to the class:
 
 ```py
 def do_echo(self, line):
     self.poutput(line)
 ```
 
-When you type input into the `cmd2` prompt, the first space delimited word is treated as the command
+When you type input into the `cmd2` prompt, the first space-delimited word is treated as the command
 name. `cmd2` looks for a method called `do_commandname`. If it exists, it calls the method, passing
 the rest of the user input as the first argument. If it doesn't exist `cmd2` prints an error
 message. As a result of this behavior, the only thing you have to do to create a new command is to
@@ -47,13 +47,14 @@ python standard library.
 
 !!! note
 
-    See [Generating Output](./generating_output.md) if you are unfamiliar with the `poutput()` method.
+    See [Generating Output](./generating_output.md) if you are unfamiliar with the
+    [poutput()][cmd2.Cmd.poutput] method.
 
 ## Statements
 
 A command is passed one argument: a string which contains all the rest of the user input. However,
-in `cmd2` this string is actually a `Statement` object, which is a subclass of `str` to retain
-backwards compatibility.
+in `cmd2` this string is actually a [Statement][cmd2.Statement] object, which is a subclass of `str`
+to retain backwards compatibility with `cmd`.
 
 `cmd2` has a much more sophisticated parsing engine than what's included in the
 [cmd](https://docs.python.org/3/library/cmd.html) module. This parsing handles:
@@ -84,7 +85,7 @@ args
 commands removed. It turns out that the "string" value of the `Statement` object has all the output
 redirection and piping clauses removed as well. Quotes remain in the string.
 
-command[and_args]{#and_args}
+command_and_args
 
 : A string of just the command and the arguments, with output redirection or piping to shell
 commands removed.
@@ -116,9 +117,11 @@ Most commands should return nothing (either by omitting a `return` statement, or
 This indicates that your command is finished (with or without errors), and that `cmd2` should prompt
 the user for more input.
 
-If you return `True` from a command method, that indicates to `cmd2` that it should stop prompting
-for user input and cleanly exit. `cmd2` already includes a `quit` command, but if you wanted to make
-another one called `finish` you could:
+If you return `True` or any
+[Truthy](https://www.freecodecamp.org/news/truthy-and-falsy-values-in-python/) value from a command
+method, that indicates to `cmd2` that it should stop prompting for user input and cleanly exit.
+`cmd2` already includes a `quit` command, but if you wanted to make another one called `finish` you
+could:
 
 ```py
 def do_finish(self, line):
@@ -128,11 +131,11 @@ def do_finish(self, line):
 
 ## Exit Codes
 
-`cmd2` has basic infrastructure to support sh/ksh/csh/bash type exit codes. The `cmd2.Cmd` object
-sets an `exit_code` attribute to zero when it is instantiated. The value of this attribute is
-returned from the `cmdloop()` call. Therefore, if you don't do anything with this attribute in your
-code, `cmdloop()` will (almost) always return zero. There are a few built-in `cmd2` commands which
-set `exit_code` to `1` if an error occurs.
+`cmd2` has basic infrastructure to support POSIX shell exit codes. The `cmd2.Cmd` object sets an
+`exit_code` attribute to zero when it is instantiated. The value of this attribute is returned from
+the `cmdloop()` call. Therefore, if you don't do anything with this attribute in your code,
+`cmdloop()` will (almost) always return zero. There are a few built-in `cmd2` commands which set
+`exit_code` to `1` if an error occurs.
 
 You can use this capability to easily return your own values to the operating system shell:
 
@@ -192,13 +195,13 @@ All other `BaseExceptions` are not caught by `cmd2` and will be raised.
 
 See [Disabling Commands](./disable_commands.md) for details of how to:
 
-- remove commands included in `cmd2`
-- hide commands from the help menu
-- disable and re-enable commands at runtime
+- Remove commands included in `cmd2`
+- Hide commands from the help menu
+- Dynamically disable and re-enable commands at runtime
 
 ## Modular Commands and Loading/Unloading Commands
 
 See [Modular Commands](./modular_commands.md) for details of how to:
 
-- Define commands in separate CommandSet modules
-- Load or unload commands at runtime
+- Define commands in separate [CommandSet][cmd2.CommandSet] modules
+- Dynamically load or unload commands at runtime