diff options
| -rw-r--r-- | docs/index.txt | 52 |
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 ------- |