Added docs for command line and using as a module.

2 files changed, 180 insertions, 0 deletions

diff --git a/docs/command_line.txt b/docs/command_line.txt
new file mode 100644
index 0000000..8ec2522
--- /dev/null
+++ b/docs/command_line.txt
@@ -0,0 +1,57 @@
+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 
+of Markdown, you may not have them installed, or you may prefer to use 
+Python-Markdown's various extensions.
+
+The Basics
+----------
+
+To use ``markdown.py`` from the command line, run it as 
+
+    python markdown.py input_file.txt
+
+or 
+
+    python 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
+    Usage: markdown.py 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)
+      --noisy               print debug messages
+      -x EXTENSION, --extension=EXTENSION
+                            load extension EXTENSION
+
+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_"):
+
+    python 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:
+
+    python markdown.py -x "footnotes(PLACE_MARKER=~~~~~~~~)" input.txt
+
diff --git a/docs/using_as_module.txt b/docs/using_as_module.txt
new file mode 100644
index 0000000..10c276c
--- /dev/null
+++ b/docs/using_as_module.txt
@@ -0,0 +1,123 @@
+Using Markdown as Python Library
+================================
+
+First and foremost, Python-Markdown is intended to be a python library module
+used by various projects to convert Markdown syntax into HTML.
+
+The Basics
+----------
+
+To use markdown as a module:
+
+    import markdown
+    html = markdown.markdown(your_text_string)
+
+Encoded Text
+------------
+
+Note that ``markdown()`` expects either a simple ASCII string or **Unicode** 
+as input and returns output as Unicode.  Do not pass encoded strings to it!
+If your input is encoded, e.g. as UTF-8, it is your responsibility to decode 
+it.  E.g.:
+
+    input_file = codecs.open("some_file.txt", mode="r", encoding="utf8")
+    text = input_file.read()
+    html = markdown.markdown(text, extensions)
+
+If you later want to write it to disk, you should encode it:
+
+    output_file = codecs.open("some_file.html", "w", encoding="utf8")
+    output_file.write(html)
+
+More Options
+------------
+
+If you want to pass more options, you can create an instance of the ``Markdown``
+class yourself and then use ``convert()`` to generate HTML:
+
+    import markdown
+    md = markdown.Markdown(extensions=['footnotes'], 
+                  extension_configs= {'footnotes' : 
+                                     ('PLACE_MARKER','~~~~~~~~')}
+                  encoding='utf8',
+                  safe_mode = True)
+    return md.convert(some_text)
+
+You should also use this method if you want to process multiple strings:
+
+    md = markdown.Markdown()
+    html1 = md.convert(text1)
+    html2 = md.convert(text2)
+
+Working with Files
+------------------
+
+While the Markdown class is only intended to work with Unicode text, some
+encoding/decoding is required for the command line features. These functions 
+and methods are only intended to fit the common use case.
+
+The ``Markdown`` class has the method ``convertFile`` which reads in a file and
+writes out to file-like-object:
+
+    md = markdown.Markdown()
+    md.convertFile(input="in.txt", output="out.html", encoding="uft8")
+
+The markdown module also includes a shortcut function ``markdownFromFile`` that
+wraps the above method.
+
+    markdown.markdownFromFile(input="in.txt", 
+                              output="out.html", 
+                              extensions=[],
+                              encoding="utf8",
+                              safe=False)
+
+In either case, if the ``output`` keyword is passed a file name (i.e.: 
+``output="out.html"``), it will try to write to a file by that name. If
+``output`` is passed a file-like-object (i.e. ``output=StringIO.StringIO()``),
+it will attempt to write out to that object. Finally, is ``output`` is 
+set to ``None``, is will write to ``stdout``.
+
+Using Extensions
+----------------
+
+One of the parameters that you can pass is a list of Extensions. Extensions 
+must be available as python modules either within the ``markdown_extensions``
+package or on your PYTHONPATH with names starting with `mdx_`, followed by the 
+name of the extension.  Thus, ``extensions=['footnotes']`` will first look for 
+the module ``markdown_extensions.footnotes``, then a module named 
+``mdx_footnotes``.   See the documentation specific to the extension you are 
+using for help in specifying configuration settings for that extension.
+
+Note that some extensions may need their state reset between each call to 
+``convert``:
+
+    html1 = md.convert(text1)
+    md.reset()
+    html2 = md.convert(text2)
+
+Safe Mode
+---------
+
+If you are using Markdown on a web system which will transform text provided 
+by untrusted users, you may want to use the "safe_mode" option which ensures 
+that the user's HTML tags are either replaced, removed or escaped. (They can 
+still create links using Markdown syntax.)
+
+* To replace HTML, set ``safe_mode="replace"`` (``safe_mode=True`` still works 
+    for backward compatibility with older versions). The HTML will be replaced 
+    with the text defined in ``markdown.HTML_REMOVED_TEXT`` which defaults to 
+    ``[HTML_REMOVED]``. To replace the HTML with something else:
+
+        markdown.HTML_REMOVED_TEXT = "--RAW HTML IS NOT ALLOWED--"
+        md = markdown.Markdown(safe_mode="replace")
+
+    **Note**: You may edit the value of ``HTML_REMOVED_TEXT`` directly in 
+    markdown.py but you will need to remember to do so every time you upgrade 
+    to a newer version of Markdown.
+
+* To remove HTML, set ``safe_mode="remove"``. Any raw HTML will be completely 
+    stripped from the text with no warning to the author.
+
+* To escape HTML, set ``safe_mode="escape"``. The HTML will be escaped and 
+    included in the document.
+