Updated docs for command line usage.

1 files changed, 62 insertions, 12 deletions

diff --git a/docs/command_line.txt b/docs/command_line.txt
index 8ec2522..1ea7302 100644
--- a/docs/command_line.txt
+++ b/docs/command_line.txt
@@ -1,28 +1,77 @@
 Using Python-Markdown on the Command Line
 =========================================
 
-While Python-Markdown is primarily a python library, it also serves as a 
-command line program. While there are many other command line implementations 
+While Python-Markdown is primarily a python library, a command line script is 
+included as well. While there are many other command line implementations 
 of Markdown, you may not have them installed, or you may prefer to use 
 Python-Markdown's various extensions.
 
+Setup
+-----
+
+Generally, you may simply call the ``python markdown.py`` file from the command 
+line. However, if you have fully installed Markdown (``setup.py install`` of 
+``easyinstall``), then the ``markdown.py`` script will have been copied to
+you Python "Scripts" directory. Different systems require different methods to
+ensure that any files in the Python "Scripts" directory are on your system 
+path.
+
+* **Windows**:
+
+    1. Assuming a default install on Windows, your "Scripts" directory is mostly
+       likely something like ``C:\\Python25\Scripts``. Verify the location of
+       your "Scripts" directory and add it to you system path.
+
+    2. Make sure Windows is setup to recognize files that end with the 
+       "``.py``" extension are associated with ``python.exe`` so that
+       you can simply call the script directly.
+
+    Note that due to a peculiarity of how things work on Windows, you cannot
+    just ``cd`` into the directory of the source distribution and run
+    ``markdown.py`` from there. It will try to import itself rather than
+    the markdown library. While a safeguard has been put in place to block this
+    from happening, if ``markdown.py`` is in the same directory as the markdown
+    library, then the safeguard blocks both from importing and the script won't
+    be able to run.
+
+* **Linux**:
+
+    As each Linux distribution is different and we can't possible document all 
+    of them here, We'll provide a few helpful pointers:
+
+    * 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
+      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
+      found, check the permissions of the file and make sure it is executable.
+
+    As an alternative, you could just ``cd`` into the directory which contains
+    the source distribution, and run it from there. However, remember that your
+    markdown text files will not likely be in that directory, so it is much more 
+    convenient to have ``markdown.py`` on your path.
+
 The Basics
 ----------
 
 To use ``markdown.py`` from the command line, run it as 
 
-    python markdown.py input_file.txt
+    $ markdown.py input_file.txt
 
 or 
 
-    python markdown.py input_file.txt > output_file.html
+    $ markdown.py input_file.txt > output_file.html
 
 More Options
+------------
 
 If you are using Python 2.3 or higher, you can also use advanced
 command line options to specify encoding or to run extensions.
 
-    $ python markdown.py
+    $ markdown.py --help
     Usage: markdown.py INPUTFILE [options]
 
     Options:
@@ -36,6 +85,9 @@ command line options to specify encoding or to run extensions.
       -s SAFE_MODE, --safe=SAFE_MODE
                             safe mode ('replace', 'remove' or 'escape'  user's
                             HTML tag)
+      -o OUTPUT_FORMAT, --output_format=OUTPUT_FORMAT
+                            Format of output. One of 'xhtml1' (default) or
+                            'html4'.
       --noisy               print debug messages
       -x EXTENSION, --extension=EXTENSION
                             load extension EXTENSION
@@ -44,14 +96,12 @@ Using Extensions
 ----------------
 
 For an extension to be ran this way it must be provided in a module
-named ``mdx_{extensionname}.py`` which should be in your python path,
-e.g. ``mdx_footnotes.py``.  It can then be invoked as by name (the
-part after "mdx_"):
+which should be in your python path (see [[writing_extensions]] for details). 
+It can then be invoked by the name of that module:
 
-    python markdown.py -x footnotes text_with_footnotes.txt > output.html
+    $ markdown.py -x footnotes text_with_footnotes.txt > output.html
 
-If the extension supports config options (see below), you can also
-pass them in as well:
+If the extension supports config options, you can pass them in as well:
 
-    python markdown.py -x "footnotes(PLACE_MARKER=~~~~~~~~)" input.txt
+    $ markdown.py -x "footnotes(PLACE_MARKER=~~~~~~~~)" input.txt