diff options
| -rw-r--r-- | docs/command_line.txt | 74 |
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 |