From cd05e3fa90eaa9b6079495a690f37ca0909c833e Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Thu, 10 Jan 2013 10:45:23 -0500 Subject: Added a list of known differences to the docs. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/index.txt | 52 ++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 44 insertions(+), 8 deletions(-) (limited to 'docs/index.txt') 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 `somelongfilename.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 `somelongfilename.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 ------- -- cgit v1.2.3 From 6c49938bad9b26f00acd6fc74f399a7ee4d87701 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Thu, 10 Jan 2013 11:07:43 -0500 Subject: Added a "goals" section to the docs. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Now, when we receive feature requests that don't fit within the scope of the Python-Markdown project, we have something to point  to in response. --- docs/index.txt | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) (limited to 'docs/index.txt') diff --git a/docs/index.txt b/docs/index.txt index e1433d5..36b05b5 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -15,6 +15,18 @@ 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 implementation of markdown 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. + Features -------- @@ -55,8 +67,9 @@ 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 +[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: -- cgit v1.2.3 From 2fc427c7aa394a4dfa841f4c78b6393caa683dfd Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Thu, 10 Jan 2013 11:27:46 -0500 Subject: Improved the goals in docs. --- docs/index.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/index.txt') diff --git a/docs/index.txt b/docs/index.txt index 36b05b5..b44f5ae 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -20,12 +20,14 @@ Goals The Python-Markdown project is developed with the following goals in mind: -* Maintain a python implementation of markdown that follows the - [syntax rules](http://daringfireball.net/projects/markdown/syntax) +* 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. + the parser to be overridden/changed/added. Features -------- -- cgit v1.2.3