aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2013-01-10 10:45:23 -0500
committerWaylan Limberg <waylan@gmail.com>2013-01-10 10:45:23 -0500
commitcd05e3fa90eaa9b6079495a690f37ca0909c833e (patch)
treeee0cea8c570a6e70ce6ab924416e45c911353cb7
parent1441de1312384c361c597d7d0ef01f4f2b68a794 (diff)
downloadmarkdown-cd05e3fa90eaa9b6079495a690f37ca0909c833e.tar.gz
markdown-cd05e3fa90eaa9b6079495a690f37ca0909c833e.tar.bz2
markdown-cd05e3fa90eaa9b6079495a690f37ca0909c833e.zip
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.
-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
-------