aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/command_line.txt74
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