Revise and clean up documentation

1 files changed, 56 insertions, 29 deletions

diff --git a/docs/transcript.rst b/docs/transcript.rst
index 5445dcd1..f0364361 100644
--- a/docs/transcript.rst
+++ b/docs/transcript.rst
@@ -3,9 +3,10 @@ Transcript based testing
 ========================
 
 A transcript is both the input and output of a successful session of a
-``cmd2``-based app which is saved to a text file. The transcript can be played
-back into the app as a unit test. You can embed regular expressions into the
-transcript to accomodate commands that produce dynamic or variable output.
+``cmd2``-based app which is saved to a text file. With no extra work on your
+part, your app can play back these transcripts as a unit test. Transcripts can
+contain regular expressions, which provide the flexibility to match responses
+from commands that produce dynamic or variable output.
 
 
 Creating a transcript
@@ -24,13 +25,19 @@ Here's a transcript created from ``python examples/example.py``:
    (Cmd) mumble maybe we could go to lunch
    well maybe we could like go to er lunch right?
 
-This transcript has three commands: you can see them on the lines that begin
-with the prompt, which in this case is ``(Cmd) ``. Following each command is
-the output generated by that command.
+This transcript has three commands: they are on the lines that begin with the
+prompt. The first command looks like this:
 
-Any lines in the transcript before the first line that begins with the prompt
-are ignored. You can take advantage of this by using the first lines of the
-transcript as comments.
+.. code-block:: none
+
+   (Cmd) say -r 3 Goodnight, Gracie
+
+
+Following each command is the output generated by that command.
+
+The transcript ignores all lines in the file until it reaches the first line
+that begins with the prompt. You can take advantage of this by using the first
+lines of the transcript as comments.
 
 .. code-block:: none
 
@@ -51,12 +58,18 @@ transcript as comments.
 
 In this example I've used several different commenting styles, and even bare
 text. It doesn't matter what you put on those beginning lines. Everything before
-the first line that starts with ``(Cmd) `` will be ignored.
+
+.. code-block:: none
+
+   (Cmd) say -r 3 Goodnight, Gracie
+
+will be ignored.
 
 If we used this transcript as-is, it would likely fail. As you can see, the
 ``mumble`` command doesn't always return the same thing. The ``mumble`` command
-inserts random words into the input. Transcripts can include regular
-expressions as a way to check for output that can change.
+inserts random words into the input. 
+
+
 
 Regular expressions can be included in the response portion of a transcript,
 and are surrounded by slashes.
@@ -69,38 +82,52 @@ and are surrounded by slashes.
    /.*\bmaybe\b.*\bcould\b.*\blunch\b.*/
 
 Without creating a tutorial on regular expressions, this one matches anything
-that has the words `maybe`, `could`, and `lunch` in that order. It doesn't
-ensure that `we` or `go` or `to` appear in the output, but it does work if
+that has the words ``maybe``, ``could``, and ``lunch`` in that order. It doesn't
+ensure that ``we`` or ``go`` or ``to`` appear in the output, but it does work if
 mumble happens to add words to the beginning or the end of the output.
 
 Since the output could be multiple lines long, ``cmd2`` uses multiline regular
-expression matching, and also uses the ``DOTALL`` flag, which subtly changes the behavior of commonly
-used special characters like `.`, `^` and `$`, so you may want to double check the
-`Python regular expression documentation
-<https://docs.python.org/3/library/re.html>`_.
+expression matching, and also uses the ``DOTALL`` flag, which subtly changes
+the behavior of commonly used special characters like ``.``, ``^`` and ``$``,
+so you may want to double check the `Python regular expression documentation
+<https://docs.python.org/3/library/re.html>`_. You also need to be careful when
+using ``\Z``, it matches after the newline at the end of the string.
 
 If your output has slashes in it, you will need to escape those slashes so the
-stuff between them is not interpred as a regular expression. In this transcript::
+stuff between them is not interpred as a regular expression. In this transcript:
+
+.. code-block:: none
 
    (Cmd) say cd /usr/local/lib/python3.6/site-packages
    /usr/local/lib/python3.6/site-packages
 
 the output contains slashes. The text between the first slash and the second
-slash, (``usr``) will be interpreted as a regular expression, and those two
+slash, will be interpreted as a regular expression, and those two
 slashes will not be included in the comparison. When replayed, this transcript
 would therefore fail. To fix it, we could either write a regular expression to
-match the path instead of specifying it verbatim, or we can escape the slashes::
+match the path instead of specifying it verbatim, or we can escape the slashes:
+
+.. code-block:: none
 
    (Cmd) say cd /usr/local/lib/python3.6/site-packages
    \/usr\/local\/lib\/python3.6\/site-packages
 
-.. note::
+.. warning::
 
-   Be careful with trailing spaces and newlines. Some terminal emulators strip
-   trailing space when you copy text from them. This could make the actual data
-   generated by your app different than the text you pasted into the
-   transcript, and it might not be readily obvious why the transcript is not
-   passing.
+   Be aware of trailing spaces and newlines. Your commands might output
+   trailing spaces which are impossible to see.
+   
+   Some terminal emulators strip trailing space when you copy text from them.
+   This could make the actual data generated by your app different than the
+   text you pasted into the transcript, and it might not be readily obvious why
+   the transcript is not passing.
+   
+   If you aren't using regular expressions, make sure the newlines at the end
+   of your transcript exactly match the output of your commands. A common cause
+   of a failing transcript is an extra or missing newline.
+   
+   If you are using regular expressions, be aware that depending on how you
+   write your regex, the newlines after the regex may or may not matter.
 
 
 Running a transcript
@@ -119,8 +146,8 @@ back and check the output. From within the ``examples/`` directory:
    OK
 
 The output will look familiar if you use ``unittest``, because that's exactly
-what happens. Each command in the transcript is run, and the output is
-``asserted`` to match expected result from the transcript.
+what happens. Each command in the transcript is run, and we ``assert`` the
+output matches the expected result from the transcript.
 
 .. note::