Merge branch 'master' into admonition

Conflicts:
	docs/extensions/index.txt
	tests/extensions/test.cfg

1 files changed, 59 insertions, 8 deletions

diff --git a/docs/index.txt b/docs/index.txt
index eb245e6..b44f5ae 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -9,12 +9,26 @@ 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.
 
 See the [installation instructions](install.html) to get started.
 
+Goals
+-----
+
+The Python-Markdown project is developed with the following goals in mind:
+
+* Maintain a Python 2 *and* Python 3 library (with an optional CLI wrapper)
+  suited to use in web server environments (never raise an exception, never 
+  write to stdout, etc.) as an implementation of the markdown parser that 
+  follows the [syntax rules](http://daringfireball.net/projects/markdown/syntax)
+  and the behavior of the original (markdown.pl) implementation as reasonably
+  as possible (see [differences](#differences) for a few exceptions).
+* Provide an [Extension API](extensions/api.html) which allows any behaviors of 
+  the parser to be overridden/changed/added.
+
 Features
 --------
 
@@ -27,13 +41,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 +65,50 @@ 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](http://daringfireball.net/projects/markdown/syntax), 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
 -------