Rename docs/*.md => docs/*.txt

The documentation uses features of Python-Markdown that are not supported on
GitHub and it's better to get a source view of the docs anyway. For example,
that way comments and bug reports can reference a specific line of a file.

Of course, it makes sense for Github to render the README, so that is left
with the `.md` file extension.

1 files changed, 81 insertions, 0 deletions

diff --git a/docs/extensions/sane_lists.txt b/docs/extensions/sane_lists.txt
new file mode 100644
index 0000000..e6c73f4
--- /dev/null
+++ b/docs/extensions/sane_lists.txt
@@ -0,0 +1,81 @@
+title:      Sane Lists Extension
+prev_title: RSS Extension
+prev_url:   rss.html
+next_title: Table of Contents Extension
+next_url:   toc.html
+
+Sane Lists
+==========
+
+Summary
+-------
+
+The Sane Lists Extension alters the behavior of the Markdown List syntax
+to be less surprising.
+
+This extension is included in the standard Markdown library.
+
+Syntax
+------
+
+Sane Lists do not allow the mixing of list types. In other words, an ordered
+list will not continue when an unordered list item is encountered and
+vice versa. For example:
+
+    1. Ordered item 1
+    2. Ordered item 2
+
+    * Unordered item 1
+    * Unordered item 2
+
+will result in the following output:
+
+    <ol>
+      <li>Ordered item 1</li>
+      <li>Ordered item 2</li>
+    </ol>
+
+    <ul>
+      <li>Unordered item 1</li>
+      <li>Unordered item 2</li>
+    </ul>
+
+Whereas the default Markdown behavior would be to generate an unordered list.
+
+Note that, unlike the default Markdown behavior, if a blank line is not
+included between list items, the different list type is ignored completely. 
+This corresponds to the behavior of paragraphs. For example:
+
+    A Paragraph.
+    * Not a list item.
+
+    1. Ordered list item.
+    * Not a separate list item.
+
+With this extension the above will result in the following output:
+
+    <p>A Paragraph.
+    * Not a list item.</p>
+
+    <ol>
+      <li>Ordered list item.
+      * Not a separate list item.</li>
+    </ol>
+
+In all other ways, Sane Lists should behave as normal Markdown lists.
+
+Usage
+-----
+
+From the Python interpreter:
+
+    >>> html = markdown.markdown(text, ['sane_lists'])
+
+To use with other extensions, just add them to the list, like this:
+
+    >>> html = markdown.markdown(text, ['def_list', 'sane_lists'])
+
+The extension can also be called from the command line using Markdown's `-x` 
+parameter:
+
+    python -m markdown -x sane_lists source.txt > output.html