Documentation edits and revisions

Author: kotfu

docs/freefeatures.rst

@@ -82,6 +82,8 @@ quotation marks if it is more than a one-word command.
 
 .. _Argparse: https://docs.python.org/3/library/argparse.html
 
+.. _output_redirection:
+
 Output redirection
 ==================
 

docs/transcript.rst

@@ -8,13 +8,12 @@ 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.
 
+.. highlight:: none
 
 Creating a transcript
 =====================
 
-Here's a transcript created from ``python examples/example.py``:
-
-.. code-block:: none
+Here's a transcript created from ``python examples/example.py``::
 
    (Cmd) say -r 3 Goodnight, Gracie
    Goodnight, Gracie
@@ -26,20 +25,15 @@ Here's a transcript created from ``python examples/example.py``:
    well maybe we could like go to er lunch right?
 
 This transcript has three commands: they are on the lines that begin with the
-prompt. The first command looks like this:
-
-.. code-block:: none
+prompt. The first command looks like this::
 
    (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
+lines of the transcript as comments::
 
    # Lines at the beginning of the transcript that do not
    ; start with the prompt i.e. '(Cmd) ' are ignored.
@@ -57,24 +51,22 @@ lines of the transcript as comments.
    maybe we could like go to er lunch right?
 
 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
-
-.. code-block:: none
+text. It doesn't matter what you put on those beginning lines. Everything before::
 
    (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. 
 
+Regular Expressions
+===================
 
+If we used the above transcript as-is, it would likely fail. As you can see,
+the ``mumble`` command doesn't always return the same thing: it inserts random
+words into the input.
 
 Regular expressions can be included in the response portion of a transcript,
-and are surrounded by slashes.
-
-.. code-block:: none
+and are surrounded by slashes::
 
    (Cmd) mumble maybe we could go to lunch
    /.*\bmaybe\b.*\bcould\b.*\blunch\b.*/
@@ -94,33 +86,36 @@ so you may want to double check the `Python regular expression documentation
 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:
-
-.. code-block:: none
+stuff between them is not interpred as a regular expression. In this transcript::
 
    (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, 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:
-
-.. code-block:: none
+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::
 
    (Cmd) say cd /usr/local/lib/python3.6/site-packages
    \/usr\/local\/lib\/python3.6\/site-packages
 
 .. warning::
 
    Be aware of trailing spaces and newlines. Your commands might output
-   trailing spaces which are impossible to see.
+   trailing spaces which are impossible to see. Instead of leaving them
+   invisible, you can add a regular expression to match them, so that you can
+   see where they are when you look at the transcript::
+   
+      (Cmd) set prompt
+      prompt: (Cmd)/ /
    
    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.
+   the transcript is not passing. Consider using :ref:`output_redirection` to
+   the clipboard or to a file to ensure you accurately capture the output of
+   your command.
 
    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
@@ -134,9 +129,7 @@ Running a transcript
 ====================
 
 Once you have created a transcript, it's easy to have your application play it
-back and check the output. From within the ``examples/`` directory:
-
-.. code-block:: none
+back and check the output. From within the ``examples/`` directory::
 
    $ python example.py --test transcript_regex.txt
    .