Added a list of known differences to the docs.

Rather than constantly responding to new bug reports for known 
differences between Python-Markdown and other implementations,
I've added this section to the docs to definitively state
our position and point people to workarounds. I'm sure some
people will still file reports, but at least I have something
to point them to.

If there are any I missed, I can always add them latter 
when they come up.

1 files changed, 44 insertions, 8 deletions

diff --git a/docs/index.txt b/docs/index.txt
index eb245e6..e1433d5 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -9,7 +9,7 @@ Python-Markdown
 This is a Python implementation of John Gruber's 
 [Markdown](http://daringfireball.net/projects/markdown/). 
 It is almost completely compliant with the reference implementation,
-though there are a few very minor differences. See John's 
+though there are a few very minor [differences](#differences). See John's 
 [Syntax Documentation](http://daringfireball.net/projects/markdown/syntax) 
 for the syntax rules.
 
@@ -27,13 +27,6 @@ features:
     supported by Unicode including bi-directional text. In fact the test suite 
     includes documents written in Russian and Arabic.
 
-* __Middle-Word Emphasis__
-
-    Python-Markdown defaults to ignoring middle-word emphasis. In other words,
-    `some_long_filename.txt` will not become `some<em>long</em>filename.txt`.
-    This can be switched off if desired. See the 
-    [Library Reference](reference.html#smart_emphasis) for details.
-
 * __Extensions__
 
     Various [extensions](extensions/index.html) are provided (including 
@@ -58,6 +51,49 @@ features:
     In addition to being a Python Library, a 
     [command line script](cli.html) is available for your convenience.
 
+Differences
+-----------
+
+While Python-Markdown strives to fully implement markdown as described in the 
+syntax rules, the rules can be interpreted in different ways and different 
+implementations occasionally vary in their behavior (see the 
+[Babelmark FAQ](http://johnmacfarlane.net/babelmark2/faq.html#what-are-some-examples-of-interesting-divergences-between-implementations)
+for some examples). Known and intentional differences found in Python-Markdown 
+are summarized below:
+
+* __Middle-Word Emphasis__
+
+    Python-Markdown defaults to ignoring middle-word emphasis. In other words,
+    `some_long_filename.txt` will not become `some<em>long</em>filename.txt`.
+    This can be switched off if desired. See the 
+    [Library Reference](reference.html#smart_emphasis) for details.
+
+* __Indentation/Tab Length__
+
+    The [syntax rules](http://daringfireball.net/projects/markdown/syntax#list) 
+    clearly state that when a list item consists of multiple paragraphs, "each 
+    subsequent paragraph in a list item **must** be indented by either 4 spaces 
+    or one tab" (emphasis added). However, many implementations do not enforce 
+    this rule and allow less than 4 spaces of indentation. The implementers of 
+    Python-Markdown consider it a bug to not enforce this rule, and therefore,
+    subsequent paragraphs of a list **must** be indented by four spaces or one
+    tab.
+
+    In the event that one would prefer different behavior,
+    [tab_length](reference.html#tab_length) can be set to whatever length is 
+    desired. Be warned however, as this will affect indentation for all aspects 
+    of the syntax (including code blocks).
+
+* __Consecutive Lists__
+
+    While the syntax rules are not clear on this, many implementations (including 
+    the original) do not end one list and start a second list when the list marker
+    (asterisks, pluses, hyphens, and numbers) changes. For consistency, 
+    Python-Markdown maintains the same behavior with no plans to change in the 
+    foreseeable future. That said, the [Sane List Extension](extensions/sane_lists.html)
+    is available to provide a less surprising behavior.
+    
+
 Support
 -------