aboutsummaryrefslogtreecommitdiffstats
path: root/docs/command_line.txt
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2011-05-18 12:58:56 -0700
committerWaylan Limberg <waylan@gmail.com>2011-05-18 12:58:56 -0700
commitf89e0dde4f14f60fcec9c8562f9d56e0384d9e24 (patch)
tree66693fa6e5d3d32c716c57159436d9f4483c7d70 /docs/command_line.txt
parent0b22d0daad5c783ffa3f7d3b292c92680a059c97 (diff)
downloadmarkdown-f89e0dde4f14f60fcec9c8562f9d56e0384d9e24.tar.gz
markdown-f89e0dde4f14f60fcec9c8562f9d56e0384d9e24.tar.bz2
markdown-f89e0dde4f14f60fcec9c8562f9d56e0384d9e24.zip
Updated command line docs to document the actual implementation. For example, the script is named "markdown_py". Also, no longer including the output of 'markdown_py --help' as that output has changed from time to time, but doesn't ever get updated here. The user can just run it if they need to. All we need to do it document that the option exists.
Diffstat (limited to 'docs/command_line.txt')
-rw-r--r--docs/command_line.txt73
1 files changed, 29 insertions, 44 deletions
diff --git a/docs/command_line.txt b/docs/command_line.txt
index d0134ea..f965bea 100644
--- a/docs/command_line.txt
+++ b/docs/command_line.txt
@@ -9,21 +9,21 @@ Python-Markdown's various extensions.
Setup
-----
-Generally, you may simply call the ``markdown`` file from the command
-line. However, if you have fully installed Markdown (``setup.py install`` or
-``easy_install``), then the ``markdown`` script will have been copied to
-you Python "Scripts" directory. Different systems require different methods to
+Generally, you will want to have the may Markdown library fully installed on your
+system (``setup.py install`` or ``easy_install markdown``) to run the command line
+script. Upon installation, the ``markdown_py`` script will have been copied to
+your Python "Scripts" directory. Different systems require different methods to
ensure that any files in the Python "Scripts" directory are on your system
path.
* **Windows**:
- Assuming a default install on Windows, your "Scripts" directory is most
- likely something like ``C:\\Python25\Scripts``. Verify the location of
+ Assuming a default install of Python on Windows, your "Scripts" directory is
+ most likely something like ``C:\\Python26\Scripts``. Verify the location of
your "Scripts" directory and add it to you system path.
- Calling ``markdown`` from th ecommand line will call the wrapper batch file
- ``markdown.bat`` in the "Scripts" directory created during install.
+ Calling ``markdown_py`` from the command line will call the wrapper batch file
+ ``markdown_py.bat`` in the "Scripts" directory created during install.
* **Linux**:
@@ -31,62 +31,47 @@ path.
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`` from the command line.
+ 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`` is on your path, but it still isn't being
+ * 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`` on your path.
+ convenient to have ``markdown_py`` on your path.
-The Basics
-----------
+__Note:__ Python-Markdown uses "markdown_py" as a script name because
+the Perl implementation has already taken the more obvious name "markdown".
+Additionally, the default Python configuration on some systems would cause a script
+named "markdown.py" to fail by importing itself rather than the markdown library.
+Therefore, the script has been named "markdown_py" as a compromise. If you prefer
+a different name for the script on your system, it is suggested that you create
+a symbolic link to `markdown_py` with your preferred name.
-To use ``markdown`` from the command line, run it as
+Usage
+-----
+
+To use ``markdown_py`` from the command line, run it as
- $ markdown input_file.txt
+ $ markdown_py input_file.txt
or
- $ markdown 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.
-
- $ markdown --help
- Usage: markdown INPUTFILE [options]
-
- Options:
- -h, --help show this help message and exit
- -f OUTPUT_FILE, --file=OUTPUT_FILE
- write output to OUTPUT_FILE
- -e ENCODING, --encoding=ENCODING
- encoding for input and output files
- -q, --quiet suppress all messages
- -v, --verbose print info messages
- -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
+ $ markdown_py input_file.txt > output_file.html
+
+For a complete list of options, run
+
+ $ markdown_py --help
Using Extensions
----------------
-For an extension to be ran this way it must be provided in a module
+For an extension to be ran from the command line it must be provided in a module
which should be in your python path (see [[writing_extensions]] for details).
It can then be invoked by the name of that module: