Tweaked the docs some more.

6 files changed, 72 insertions, 56 deletions

diff --git a/docs/cli.txt b/docs/cli.txt
index 719bc0c..ff19501 100644
--- a/docs/cli.txt
+++ b/docs/cli.txt
@@ -17,21 +17,36 @@ Generally, you will want to have the Markdown library fully installed on your
 system to run the command line script. See the 
 [Installation instructions](install.html) for details.
 
-Assuming the `python` executable is on your system path, just run the following:
+Python-Markdown's command line script takes advantage of Python's `-m` flag.
+Therefore, assuming the python executable is on your system path, use the 
+following format:
 
-    python -m markdown [options] [args]
+    $ python -m markdown [options] [args]
 
-That will run the module as a script. Note that on older Python versions (2.6), 
-you may need to specify the appropriate module:
+That will run the module as a script with the options and args provided. 
 
-    python -m markdown.__main__ [options] [args]
+!!! Note 
+    Unfortunately, Python 2.6 does not fully support the `-m` flag. Therefore, you 
+    may need to specify the module in which the command line script exists 
+    (`markdown.__main__`):
 
-Use the `--help` option for available options:
+        $ python -m markdown.__main__ [options] [args]
 
-    python -m markdown --help
+At its most basic usage, one would simply pass in a file name as the only argument:
 
-If you don't want to call the python executable directly, follow the 
-instructions below:
+    $ python -m markdown input_file.txt
+
+Piping input and output (on STDIN and STDOUT) is fully supported as well. 
+For example:
+
+    $ echo "Some **Markdown** text." | python -m markdown > output.html
+
+Use the `--help` option for a list all available options and args:
+
+    $ python -m markdown --help
+
+If you don't want to call the python executable directly (using the `-m` flag), 
+follow the instructions below to use a wrapper script:
 
 Setup
 -----
@@ -58,8 +73,8 @@ path.
     * Some systems will automatically install the script on your path. Try it 
       and see if it works. Just run ``markdown_py`` from the command line.
 
-    * Other systems may maintain a separate "Scripts" directory which you
-      need to add to your path. Find it (check with your distribution) and
+    * Other systems may maintain a separate "Scripts" ("bin") directory which 
+      you need to add to your path. Find it (check with your distribution) and
       either add it to your path or make a symbolic link to it from your path.
 
     * If you are sure ``markdown_py`` is on your path, but it still isn't being
diff --git a/docs/extensions/api.txt b/docs/extensions/api.txt
index ac840f9..bc06154 100644
--- a/docs/extensions/api.txt
+++ b/docs/extensions/api.txt
@@ -594,7 +594,7 @@ the module and call the `makeExtension` function to initiate your extension.
 
 The "name" of your extension must be a string consisting of the importable path to
 your module using Python's dot notation. Therefore, if you are providing a library
-to your users and would like to include a custom markdown extensions with your 
+to your users and would like to include a custom markdown extensions within your 
 library, that extension would be named `"mylib.mdext.myext"` where `mylib/mdext/myext.py`
 contains the `makeExtension` function and the `mylib` directory is on the PYTHONPATH.
 
diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt
index 57f81ca..2e15e58 100644
--- a/docs/extensions/code_hilite.txt
+++ b/docs/extensions/code_hilite.txt
@@ -51,67 +51,67 @@ block contains and each one has a different result.
 
 [syntax]: http://daringfireball.net/projects/markdown/syntax#precode
 
-###SheBang (with path)
+* ###SheBang (with path)
 
-If the first line of the codeblock contains a shebang, the language is derived
-from that and line numbers are used.
+    If the first line of the codeblock contains a shebang, the language is derived
+    from that and line numbers are used.
+
+            #!/usr/bin/python
+            # Code goes here ...
+
+    Will result in:
 
         #!/usr/bin/python
         # Code goes here ...
 
-Will result in:
 
-    #!/usr/bin/python
-    # Code goes here ...
+* ###SheBang (no path)
 
+    If the first line contains a shebang, but the shebang line does not contain a
+    path (a single `/` or even a space), then that line is removed from the code
+    block before processing. Line numbers are used.
 
-###SheBang (no path)
+            #!python
+            # Code goes here ...
 
-If the first line contains a shebang, but the shebang line does not contain a
-path (a single `/` or even a space), then that line is removed from the code
-block before processing. Line numbers are used.
+    Will result in:
 
-        #!python
         # Code goes here ...
 
-Will result in:
+* ###Colons
 
-    # Code goes here ...
+    If the first line begins with three or more colons, the text following the
+    colons identifies the language. The first line is removed from the code block
+    before processing and line numbers are not used.
 
-####Colons
+            :::python
+            # Code goes here ...
 
-If the first line begins with three or more colons, the text following the
-colons identifies the language. The first line is removed from the code block
-before processing and line numbers are not used.
+    Will result in:
 
-        :::python
         # Code goes here ...
 
-Will result in:
+* ###When No Language is Defined
 
-    # Code goes here ...
+    CodeHilite is completely backward compatible so that if a code block is
+    encountered that does not define a language, the block is simply wrapped in
+    `<pre>` tags and output. 
 
-###When No Language is Defined
+            # Code goes here ...
 
-CodeHilite is completely backward compatible so that if a code block is
-encountered that does not define a language, the block is simply wrapped in
-`<pre>` tags and output. 
+    Will result in:
 
         # Code goes here ...
 
-Will result in:
-
-    # Code goes here ...
+    Lets see the source for that:
 
-Lets see the source for that:
+        <div class="codehilite"><pre><code># Code goes here ...
+        </code></pre></div>
 
-    <div class="codehilite"><pre><code># Code goes here ...
-    </code></pre></div>
-
-!!! Note
-    When no language is defined, the Pygments highlighting engine will try to guess 
-    the language (unless `guess_lang` is set to `False`). Upon failure, the same 
-    behavior will happen as described above.
+    !!! Note
+        When no language is defined, the Pygments highlighting engine will try to guess 
+        the language (unless `guess_lang` is set to `False`). Upon failure, the same 
+        behavior will happen as described above.
 
 Usage
 -----
diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt
index 99ca8c7..934c1d6 100644
--- a/docs/extensions/index.txt
+++ b/docs/extensions/index.txt
@@ -20,7 +20,7 @@ See the [Library Reference](../reference.html#extensions) for more details.
 
 From the command line, specify an extension with the `-x` option. 
 
-    python -m markdown -x footnotes -x tables input.txt > output.html
+    $ python -m markdown -x footnotes -x tables input.txt > output.html
 
 See the [Command Line docs](../cli.html) or use the `--help` option for more details.
 
diff --git a/docs/index.txt b/docs/index.txt
index b0372d8..edf1cbd 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -26,6 +26,7 @@ The Python-Markdown project is developed with the following goals in mind:
   follows the [syntax rules](http://daringfireball.net/projects/markdown/syntax)
   and the behavior of the original (markdown.pl) implementation as reasonably
   as possible (see [differences](#differences) for a few exceptions).
+
 * Provide an [Extension API](extensions/api.html) which makes it possible
   to change and/or extend the behavior of the parser.
 
diff --git a/docs/release-2.3.txt b/docs/release-2.3.txt
index 956a303..146ab53 100644
--- a/docs/release-2.3.txt
+++ b/docs/release-2.3.txt
@@ -8,7 +8,7 @@ Python-Markdown 2.3 Release Notes
 =================================
 
 We are pleased to release Python-Markdown 2.3 which adds one new extension,
-remove an old extension, and now runs on both Python 2 and Python 3
+removes an old extension, and now runs on both Python 2 and Python 3
 without running the 2to3 conversion tool. See the list of changes below for
 details.
 
@@ -19,8 +19,8 @@ Backwards-incompatible Changes
 
 * Support has been dropped for Python 2.5. No guarantees are made that the
 library will work in any version of Python lower than 2.6. As all supported
-Python versions include the ElementTree library, Python-Markdown no longer
-will try to import a third-party installation of ElementTree.
+Python versions include the ElementTree library, Python-Markdown will no 
+longer try to import a third-party installation of ElementTree.
 
 * All classes are now "new-style" classes. In other words, all classes
 subclass from 'object'. While this is not likely to affect most users, 
@@ -28,7 +28,7 @@ extension authors may need to make a few minor adjustments to their code.
 
 * "safe_mode" has been further restricted. Markdown formated links must be
 of a known whitelisted scheme when in "safe_mode" or the url is discarded.
-The whitelesited schemes are: 'http', 'https', 'ftp', 'ftps', 'mailto',
+The whitelisted schemes are: 'http', 'https', 'ftp', 'ftps', 'mailto', and
 'news'. Schemeless urls are also permitted, but are checked in other ways - 
 as they have been for some time.
 
@@ -39,7 +39,7 @@ you will need to update your code accordingly. No changes are necessary if
 you are outputing XHTML (the default) or HTML4.
 
 * The "force_linenos" config setting of the CodeHilite extension has been
-marked as Pending Deprecation and a new setting "linenums" has been added to
+marked as **Pending Deprecation** and a new setting "linenums" has been added to
 replace it. See documentation for the [CodeHilite Extension] for an explanation
 of the new "linenums" setting. The new setting will honor the old 
 "force_linenos" if it is set, but it will raise a PendingDeprecationWarning 
@@ -63,10 +63,10 @@ subdirectory of another project. The various files within the library will
 still import each other properly even though 'markdown' may not be in Python's
 root namespace.
 
-* Added the [Admonition Extension] which implements [rST-style][rST] 
-admonitions to the Markdown syntax. However, be warned that this extension 
+* The [Admonition Extension] has been added, which implements [rST-style][rST] 
+admonitions in the Markdown syntax. However, be warned that this extension 
 is experimental and the syntax and behavior is still subject to change. Please 
-try it out and report bugs/improvements.
+try it out and report bugs and/or improvements.
 
 [Admonition Extension]: extensions/admonition.html
 [rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions