Add documentation for the history command.

Author: kotfu

docs/freefeatures.rst

@@ -29,9 +29,9 @@ Simply include one command per line, typed exactly as you would inside a ``cmd2`
 Comments
 ========
 
-Any command line input where the first non-whitespace character is a # will be treated as a comment.
-This means any # character appearing later in the command will be treated as a literal. The same
-applies to a # in the middle of a multiline command, even if it is the first character on a line.
+Any command line input where the first non-whitespace character is a `#` will be treated as a comment.
+This means any `#` character appearing later in the command will be treated as a literal. The same
+applies to a `#` in the middle of a multiline command, even if it is the first character on a line.
 
 Comments can be useful in :ref:`scripts`, but would be pointless within an interactive session.
 
@@ -269,9 +269,198 @@ the readline history.
 
 .. automethod:: cmd2.cmd2.Cmd.__init__
 
-``cmd2`` makes a third type of history access available with the **history** command:
+``cmd2`` makes a third type of history access available with the `history` command. Each time
+the user enters a command, ``cmd2`` saves the input. The `history` command lets you do interesting
+things with that saved input. The examples to follow all assume that you have entered the
+following commands::
 
-.. automethod:: cmd2.cmd2.Cmd.do_history
+    (Cmd) alias create one !echo one
+    Alias 'one' created
+    (Cmd) alias create two !echo two
+    Alias 'two' created
+    (Cmd) alias create three !echo three
+    Alias 'three' created
+    (Cmd) alias create four !echo four
+    Alias 'four' created
+
+In it's simplest form, the `history` command displays previously entered commands. With no
+additional arguments, it displays all previously entered commands::
+
+    (Cmd) history
+        1  alias create one !echo one
+        2  alias create two !echo two
+        3  alias create three !echo three
+        4  alias create four !echo four
+
+If you give a positive integer as an argument, then it only displays the specified command::
+
+    (Cmd) history 4
+        4  alias create four !echo four
+
+If you give a negative integer *N* as an argument, then it display the *Nth* last command.
+For example, if you give `-1` it will display the last command you entered. If you give `-2`
+it will display the next to last command you entered, and so forth::
+
+    (Cmd) history -2
+        3  alias create three !echo three
+
+You can use a similar mechanism to display a range of commands. Simply give two command numbers
+separated by `..` or `:`, and you will see all commands between those two numbers::
+
+    (Cmd) history 2:3
+        2  alias create two !echo two
+        3  alias create three !echo three
+
+If you omit the first number, it will start at the beginning. If you omit the last number, it
+will continue to the end::
+
+    (Cmd) history :2
+        1  alias create one !echo one
+        2  alias create two !echo two
+    (Cmd) history 2:
+        2  alias create two !echo two
+        3  alias create three !echo three
+        4  alias create four !echo four
+
+You can use negative numbers as either the first or second number of the range (but not both). If
+you want to display the last three commands entered::
+
+    (Cmd) history -- -3:
+        2  alias create two !echo two
+        3  alias create three !echo three
+        4  alias create four !echo four
+
+Notice the double dashes. These are required because the history command uses `argparse` to parse
+the command line arguments. For reasons I do not understand, `argparse` thinks `-3:` is an
+option, not an argument, but it thinks `-3` is an argument.
+
+There is no zeroth command, so don't ask for it. If you are a python programmer, you've
+probably noticed this looks a lot like the slice syntax for lists and arrays. It is,
+with the exception that the first history command is 1, where the first element in
+a python array is 0.
+
+Besides selecting previous commands by number, you can also search for them. You can use a simple
+string search::
+
+    (Cmd) history two
+        2  alias create two !echo two
+
+Or a regular expression search by enclosing your regex in slashes::
+
+    (Cmd) history '/te\ +th/'
+        3  alias create three !echo three
+
+If your regular expression contains any characters that `argparse` finds
+interesting, like dash or plus, you also need to enclose your regular expression
+in quotation marks.
+
+This all sounds great, but doesn't it seem like a bit of overkill to have all
+these ways to select commands if all we can do is display them? Turns out,
+displaying history commands is just the beginning. The history command can
+perform many other actions:
+
+- running previously entered commands
+- saving previously entered commands to a text file
+- opening previously entered commands in your favorite text editor
+- running previously entered commands, saving the commands and their output to a text file
+- clearing the history of entered commands
+
+Each of these actions is invoked using a command line option. The `-r` or
+`--run` option runs one or more previously entered commands. To run command
+number 1::
+
+    (Cmd) history --run 1
+
+To rerun the last two commands (there's that double dash again to make argparse
+stop looking for options)::
+
+    (Cmd) history -r -- -2:
+
+Say you want to re-run some previously entered commands, but you would really
+like to make a few changes to them before doing so. When you use the `-e` or
+`--edit` option, `history` will write the selected commands out to a text file,
+and open that file with a text editor. You make whatever changes, additions, or
+deletions, you want. When you leave the text editor, all the commands in the
+file are executed. To edit and then re-run commands 2-4 you would::
+
+    (Cmd) history --edit 2:4
+
+If you want to save the commands to a text file, but not edit and re-run them,
+use the `-o` or `--output-file` option. This is a great way to create
+:ref:`scripts`, which can be loaded and executed using the `load` command. To
+save the first 5 commands entered in this session to a text file::
+
+    (Cmd) history :5 -o history.txt
+
+The `history` command can also save both the commands and their output to a text
+file. This is called a transcript. See :doc:`transcript` for more information on
+how transcripts work, and what you can use them for. To create a transcript use
+the `-t` or `--transcription` option::
+
+    (Cmd) history 2:3 --transcript transcript.txt
+
+The `--transcript` option implies `--run`: the commands must be re-run in order
+to capture their output to the transcript file.
+
+The last action the history command can perform is to clear the command history
+using `-c` or `--clear`::
+
+    (Cmd) history -c
+
+In addition to these five actions, the `history` command also has some options
+to control how the output is formatted. With no arguments, the `history` command
+displays the command number before each command. This is great when displaying
+history to the screen because it gives you an easy reference to identify
+previously entered commands. However, when creating a script or a transcript,
+the command numbers would prevent the script from loading properly. The `-s` or
+`--script` option instructs the `history` command to suppress the line numbers.
+This option is automatically set by the `--output-file`, `--transcript`, and
+`--edit` options. If you want to output the history commands with line numbers
+to a file, you can do it with output redirection::
+
+    (Cmd) history 1:4 > history.txt
+
+You might use `-s` or `--script` on it's own if you want to display history
+commands to the screen without line numbers, so you can copy them to the
+clipboard::
+
+    (Cmd) history -s 1:3
+
+`cmd2` supports both aliases and macros, which allow you to substitute a short,
+more convenient input string with a longer replacement string. Say we create an
+alias like this, and then use it::
+
+    (Cmd) alias create ls shell ls -aF
+    Alias 'ls' created
+    (Cmd) ls -d h*
+    history.txt     htmlcov/
+
+By default, the `history` command shows exactly what we typed::
+
+    (Cmd) history
+        1  alias create ls shell ls -aF
+        2  ls -d h*
+
+There are two ways to modify that display so you can see what aliases and macros
+were expanded to. The first is to use `-x` or `--expanded`. These options show
+the expanded command instead of the entered command::
+
+    (Cmd) history -x
+        1  alias create ls shell ls -aF
+        2  shell ls -aF -d h*
+
+If you want to see both the entered command and the expanded command, use the
+`-v` or `--verbose` option::
+
+    (Cmd) history -v
+        1  alias create ls shell ls -aF
+        2  ls -d h*
+        2x shell ls -aF -d h*
+
+If the entered command had no expansion, it is displayed as usual. However, if
+there is some change as the result of expanding macros and aliases, then the
+entered command is displayed with the number, and the expanded command is
+displayed with the number followed by an `x`.
 
 .. _`Readline Emacs editing mode`: http://readline.kablamo.org/emacs.html
 
@@ -295,7 +484,6 @@ with automatically included ``do_`` methods.
 ( ``!`` is a shortcut for ``shell``; thus ``!ls``
 is equivalent to ``shell ls``.)
 
-
 Transcript-based testing
 ========================