Fix grammar and spelling issues in documentation and some outdated info (#1509)

* Fix grammar and spelling issues in documentation and some outdated info

* Address PR comments

* Recreated screenshot used in the top-level README due to a bug that has been fixed.

Author: tleonhardt

cmd2.png

@@ -7,9 +7,9 @@ described by [Write The Docs](http://www.writethedocs.org)
 
 In addition:
 
-- We have gone to great lengths to retain compatibility with the standard library cmd, the
-  documentation should make it easy for developers to understand how to move from cmd to cmd2, and
-  what benefits that will provide
+- We have gone to great lengths to retain compatibility with the standard library `cmd`, the
+  documentation should make it easy for developers to understand how to move from `cmd` to `cmd2`,
+  and what benefits that will provide
 - We should provide both descriptive and reference documentation.
 - API reference documentation should be generated from docstrings in the code
 - Documentation should include rich hyperlinking to other areas of the documentation, and to the API
@@ -18,7 +18,7 @@ In addition:
 ## Style Checker
 
 We strongly encourage all developers to use [Prettier](https://prettier.io/) for formatting all
-**Markdown** and YAML files. The easiest way to do this is to integrated it with your IDE and
+**Markdown** and YAML files. The easiest way to do this is to integrate it with your IDE and
 configure your IDE to format on save. You can also install `prettier` either using `npm` or OS
 package manager such as `brew` or `apt`.
 
@@ -28,7 +28,7 @@ All source files in the documentation must:
 
 - have all lower case file names
 - if the name has multiple words, separate them with an underscore
-- end in '.rst'
+- end in '.md'
 
 ## Indenting
 
@@ -42,15 +42,15 @@ html.
 
 ## Titles and Headings
 
-Reference the [Markdown Basic Syntax](https://www.markdownguide.org/basic-syntax/) for synatx basics
+Reference the [Markdown Basic Syntax](https://www.markdownguide.org/basic-syntax/) for syntax basics
 or [The Markdown Guide](https://www.markdownguide.org/) for a more complete reference.
 
 ## Inline Code
 
 Code blocks can be created in two ways:
 
 - Indent the block - this will show as a monospace code block, but won't include highighting
-- use the triple backticks followed by the code language, e.e. `python` and close with triple
+- use the triple backticks followed by the code language, e.g. `python` and close with triple
   backticks
 
 If you want to show non-Python code, like shell commands, then use a different language such as
@@ -65,7 +65,7 @@ See the [Links](https://www.markdownguide.org/basic-syntax/) Markdown syntax doc
 The API documentation is mostly pulled from docstrings in the source code using the MkDocs
 [mkdocstrings](https://mkdocstrings.github.io/) plugin.
 
-When using `mkdocstinrgs`, it must be preceded by a blank line before and after, i.e.:
+When using `mkdocstrings`, it must be preceded by a blank line before and after, i.e.:
 
 ```markdown
 ::: cmd2.history.History

docs/doc_conventions.md

@@ -17,8 +17,8 @@ However, there are some limitations to this way of using `cmd2`, mainly that `cm
 loop of a program. This can be unnecessarily restrictive and can prevent using libraries which
 depend on controlling their own event loop.
 
-Many Python concurrency libraries involve or require an event loop which they are in control of such
-as [asyncio](https://docs.python.org/3/library/asyncio.html), [gevent](http://www.gevent.org/),
+Many Python concurrency libraries involve or require an event loop which they are in control of,
+such as [asyncio](https://docs.python.org/3/library/asyncio.html), [gevent](http://www.gevent.org/),
 [Twisted](https://twistedmatrix.com), etc.
 
 `cmd2` applications can be executed in a fashion where `cmd2` doesn't own the main loop for the
@@ -44,7 +44,8 @@ if __name__ == '__main__':
     app.postloop()
 ```
 
-The `cmd2.Cmd.runcmds_plus_hooks()` method runs multiple commands via `cmd2.Cmd.onecmd_plus_hooks`.
+The `cmd2.Cmd.runcmds_plus_hooks()` method runs multiple commands via
+`cmd2.Cmd.onecmd_plus_hooks()`.
 
 The `cmd2.Cmd.onecmd_plus_hooks()` method will do the following to execute a single command in a
 normal fashion:

docs/examples/alternate_event_loops.md

@@ -81,15 +81,15 @@ $ python getting_started.py
 (Cmd) set
 ```
 
-you will see our `maxrepeats` setting show up with it's default value of `3`.
+you will see our `maxrepeats` setting show up with its default value of `3`.
 
 ## Create A Command
 
 Now we will create our first command, called `speak` which will echo back whatever we tell it to
 say. We are going to use an [argument processor](../features/argument_processing.md) so the `speak`
-command can shout and talk piglatin. We will also use some built in methods for
+command can shout and talk pig latin. We will also use some built in methods for
 [generating output](../features/generating_output.md). Add this code to `getting_started.py`, so
-that the `speak_parser` attribute and the `do_speak()` method are part of the `CmdLineApp()` class:
+that the `speak_parser` attribute and the `do_speak()` method are part of the `FirstApp()` class:
 
 ```py
 speak_parser = cmd2.Cmd2ArgumentParser()
@@ -146,13 +146,13 @@ At the end of the method, we use our `maxrepeats` setting as an upper limit to t
 we will print the output.
 
 The last thing you'll notice is that we used the `self.poutput()` method to display our output.
-`poutput()` is a method provided by `cmd2`, which I strongly recommend you use anytime you want to
+`poutput()` is a method provided by `cmd2`, which I strongly recommend you use any time you want to
 [generate output](../features/generating_output.md). It provides the following benefits:
 
 1.  Allows the user to redirect output to a text file or pipe it to a shell process
-1.  Gracefully handles `BrokenPipeWarning` exceptions for redirected output
+1.  Gracefully handles `BrokenPipeError` exceptions for redirected output
 1.  Makes the output show up in a [transcript](../features/transcripts.md)
-1.  Honors the setting to [strip embedded ansi sequences](../features/settings.md#allow_style)
+1.  Honors the setting to [strip embedded ANSI sequences](../features/settings.md#allow_style)
     (typically used for background and foreground colors)
 
 Go run the script again, and try out the `speak` command. Try typing `help speak`, and you will see
@@ -215,7 +215,7 @@ Some use cases benefit from the ability to have commands that span more than one
 you might want the ability for your user to type in a SQL command, which can often span lines and
 which are terminated with a semicolon. Let's add a
 [multiline command](../features/multiline_commands.md) to our application. First we'll create a new
-command called `orate`. This code shows both the definition of our `speak`command, and the`orate`
+command called `orate`. This code shows both the definition of our `speak` command, and the `orate`
 command:
 
 ```py
@@ -267,9 +267,9 @@ persist between invocations of your application, you'll need to do a little work
 
 Users can access command history using two methods:
 
-- the [readline](https://docs.python.org/3/library/readline.html) library which provides a python
+- The [readline](https://docs.python.org/3/library/readline.html) library which provides a Python
   interface to the [GNU readline library](https://en.wikipedia.org/wiki/GNU_Readline)
-- the `history` command which is built-in to `cmd2`
+- The `history` command which is built-in to `cmd2`
 
 From the prompt in a `cmd2`-based application, you can press `Control-p` to move to the previously
 entered command, and `Control-n` to move to the next command. You can also search through the
@@ -280,10 +280,10 @@ details, including all the available commands, and instructions for customizing
 The `history` command allows a user to view the command history, and select commands from history by
 number, range, string search, or regular expression. With the selected commands, users can:
 
-- re-run the commands
-- edit the selected commands in a text editor, and run them after the text editor exits
-- save the commands to a file
-- run the commands, saving both the commands and their output to a file
+- Re-run the commands
+- Edit the selected commands in a text editor, and run them after the text editor exits
+- Save the commands to a file
+- Run the commands, saving both the commands and their output to a file
 
 Learn more about the `history` command by typing `history -h` at any `cmd2` input prompt, or by
 exploring [Command History For Users](../features/history.md#for-users).

docs/examples/getting_started.md

@@ -9,10 +9,10 @@ following for you:
 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. Adds the usage message from the argument parser to your command.
-1. Checks if the `-h/--help` option is present, and if so, display the help message for the command
+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 importable from `cmd2`.
+These features are all provided by the `@with_argparser` decorator which is imported from `cmd2`.
 
 See the
 [argparse_example](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_example.py)
@@ -49,7 +49,7 @@ argparser.add_argument('-r', '--repeat', type=int, help='output [n] times')
 argparser.add_argument('word', nargs='?', help='word to say')
 
 @with_argparser(argparser)
-def do_speak(self, opts)
+def do_speak(self, opts):
     """Repeats what you tell me to."""
     arg = opts.word
     if opts.piglatin:
@@ -91,7 +91,7 @@ the `help tag` command displays:
 ```text
 usage: tag [-h] tag content [content ...]
 
-create a html tag
+create an HTML tag
 
 positional arguments:
   tag         tag
@@ -101,13 +101,13 @@ optional arguments:
   -h, --help  show this help message and exit
 ```
 
-If you would prefer you can set the `description` while instantiating the `argparse.ArgumentParser`
+If you would prefer, you can set the `description` while instantiating the `argparse.ArgumentParser`
 and leave the docstring on your method empty:
 
 ```py
 from cmd2 import Cmd2ArgumentParser, with_argparser
 
-argparser = Cmd2ArgumentParser(description='create an html tag')
+argparser = Cmd2ArgumentParser(description='create an HTML tag')
 argparser.add_argument('tag', help='tag')
 argparser.add_argument('content', nargs='+', help='content to surround with tag')
 @with_argparser(argparser)
@@ -121,7 +121,7 @@ Now when the user enters `help tag` they see:
 ```text
 usage: tag [-h] tag content [content ...]
 
-create an html tag
+create an HTML tag
 
 positional arguments:
   tag         tag
@@ -136,7 +136,7 @@ To add additional text to the end of the generated help message, use the `epilog
 ```py
 from cmd2 import Cmd2ArgumentParser, with_argparser
 
-argparser = Cmd2ArgumentParser(description='create an html tag',
+argparser = Cmd2ArgumentParser(description='create an HTML tag',
                                 epilog='This command cannot generate tags with no content, like <br/>.')
 argparser.add_argument('tag', help='tag')
 argparser.add_argument('content', nargs='+', help='content to surround with tag')
@@ -151,7 +151,7 @@ Which yields:
 ```text
 usage: tag [-h] tag content [content ...]
 
-create an html tag
+create an HTML tag
 
 positional arguments:
   tag         tag
@@ -195,7 +195,7 @@ class CmdLineApp(cmd2.Cmd):
             self.poutput(arg)
 ```
 
-If you don't want to access the additional attributes on the string passed to you`do_*` method you
+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:
@@ -320,7 +320,7 @@ def do_foo(self, args: argparse.Namespace) -> None:
 ```
 
 However, if you do NOT want the custom decorator runtime behavior to occur even in the case of an
-`argparse` error, then that decorator needs to go **before** the `arpgarse` one, e.g.:
+`argparse` error, then that decorator needs to go **before** the `argparse` one, e.g.:
 
 ```py
 @my_decorator
@@ -338,9 +338,9 @@ example demonstrates both above cases in a concrete fashion.
 `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_statement` - `cmd2.Cmd2AttributeWrapper` object containing `cmd2.Statement` object that was
-  created when parsing the command line.
+- `cmd2_statement` - `cmd2.Cmd2AttributeWrapper` object containing the `cmd2.Statement` object that
+  was created when parsing the command line.
 - `cmd2_handler` - `cmd2.Cmd2AttributeWrapper` object containing a subcommand handler function or
   `None` if one was not set.
-- `__subcmd_handler__` - used by cmd2 to identify the handler for a subcommand created with
+- `__subcmd_handler__` - used by cmd2 to identify the handler for a subcommand created with the
   `@cmd2.as_subcommand_to` decorator.

docs/features/argument_processing.md

@@ -89,7 +89,7 @@ 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 nonessential feedback
+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
 ```

docs/features/builtin_commands.md

@@ -12,9 +12,9 @@ clipboard by ending the command with a greater than symbol:
 mycommand args >
 ```
 
-Think of it as though you are redirecting output to an unnamed, ephemeral place, you know, like the
-clipboard. You can also append output to the current contents of the clipboard by ending the command
-with two greater than symbols:
+Think of it as redirecting the output to an unnamed, ephemeral place: the clipboard. You can also
+append output to the current contents of the clipboard by ending the command with two greater than
+symbols:
 
 ```text
 mycommand arg1 arg2 >>

docs/features/clipboard.md

@@ -28,9 +28,9 @@ if __name__ == '__main__':
     sys.exit(c.cmdloop())
 ```
 
-This application subclasses `cmd2.Cmd` but has no code of it's own, so all functionality (and
-there's quite a bit) is inherited. Lets 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):
@@ -55,7 +55,7 @@ A command is passed one argument: a string which contains all the rest of the us
 in `cmd2` this string is actually a `Statement` object, which is a subclass of `str` to retain
 backwards compatibility.
 
-`cmd2` has a much more sophsticated parsing engine than what's included in the
+`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:
 
 - quoted arguments
@@ -105,7 +105,7 @@ terminator
 this attribute will tell you which one the user typed.
 
 For many simple commands, like the `echo` command above, you can ignore the `Statement` object and
-all of it's attributes and just use the passed value as a string. You might choose to use the `argv`
+all of its attributes and just use the passed value as a string. You might choose to use the `argv`
 attribute to do more sophisticated argument processing. Before you go too far down that path, you
 should check out the [Argument Processing](./argument_processing.md) functionality included with
 `cmd2`.
@@ -149,7 +149,7 @@ def do_bail(self, line):
     """Exit the application"""
     self.perror("fatal error, exiting")
     self.exit_code = 2
-    return true
+    return True
 
 if __name__ == '__main__':
     import sys
@@ -174,8 +174,8 @@ Raising `SystemExit(code)` or calling `sys.exit(code)` in a command or hook func
 
 You may choose to catch and handle any exceptions which occur in a command method. If the command
 method raises an exception, `cmd2` will catch it and display it for you. The
-[debug setting](./settings.md#debug) controls how the exception is displayed. If `debug` is `false`,
-which is the default, `cmd2` will display the exception name and message. If `debug` is `true`,
+[debug setting](./settings.md#debug) controls how the exception is displayed. If `debug` is `False`,
+which is the default, `cmd2` will display the exception name and message. If `debug` is `True`,
 `cmd2` will display a traceback, and then display the exception name and message.
 
 There are a few exceptions which commands can raise that do not print as described above:
@@ -186,7 +186,7 @@ There are a few exceptions which commands can raise that do not print as describ
 - `KeyboardInterrupt` - raised if running in a text script and `stop` isn't already True to stop the
   script
 
-All other `BaseExceptions` are not caught by `cmd2` and will be raised
+All other `BaseExceptions` are not caught by `cmd2` and will be raised.
 
 ## Disabling or Hiding Commands
 

docs/features/commands.md

@@ -85,8 +85,8 @@ instance, `ArgparseCompleter` sets it to False when displaying completion hints.
 
 ## Tab Completion Using argparse Decorators {: #argparse-based }
 
-When using one the argparse-based [cmd2.decorators](../api/decorators.md), `cmd2` provides automatic
-tab completion of flag names.
+When using one of the argparse-based [cmd2.decorators](../api/decorators.md), `cmd2` provides
+automatic tab completion of flag names.
 
 Tab completion of argument values can be configured by using one of three parameters to
 `argparse.ArgumentParser.add_argument`
@@ -95,25 +95,26 @@ Tab completion of argument values can be configured by using one of three parame
 - `choices_provider`
 - `completer`
 
-See the [arg_decorators](https://github.com/python-cmd2/cmd2/blob/main/examples/arg_decorators.py)
+See the
+[argparse_example](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_example.py)
 example for a demonstration of how to use the `choices` parameter. See the
 [argparse_completion](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_completion.py)
 example for a demonstration of how to use the `choices_provider` parameter. See the
-[arg_decorators](https://github.com/python-cmd2/cmd2/blob/main/examples/arg_decorators.py) or
+[argparse_example](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_example.py) or
 [argparse_completion](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_completion.py)
 example for a demonstration of how to use the `completer` parameter.
 
 When tab completing flags or argument values for a `cmd2` command using one of these decorators,
 `cmd2` keeps track of state so that once a flag has already previously been provided, it won't
-attempt to tab complete it again. When no completion results exists, a hint for the current argument
+attempt to tab complete it again. When no completion results exist, a hint for the current argument
 will be displayed to help the user.
 
 ## CompletionItem For Providing Extra Context
 
 When tab completing things like a unique ID from a database, it can often be beneficial to provide
 the user with some extra context about the item being completed, such as a description. To
-facilitate this, `cmd2` defines the `cmd2.argparse_custom.CompletionItem` class which can be
-returned from any of the 3 completion parameters: `choices`, `choices_provider`, and `completer`.
+facilitate this, `cmd2` defines the `cmd2.CompletionItem` class which can be returned from any of
+the 3 completion parameters: `choices`, `choices_provider`, and `completer`.
 
 See the
 [argparse_completion](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_completion.py)