aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/index.txt52
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
-------