Added first draft of 2.6 release notes.

1 files changed, 133 insertions, 0 deletions

diff --git a/docs/release-2.6.txt b/docs/release-2.6.txt
new file mode 100644
index 0000000..0724700
--- /dev/null
+++ b/docs/release-2.6.txt
@@ -0,0 +1,133 @@
+title:      Release Notes for v2.6
+prev_title: Change Log
+prev_url:   change_log.html
+next_title: Release Notes for v2.5
+next_url:   release-2.5.html
+
+Python-Markdown 2.6 Release Notes
+=================================
+
+We are pleased to release Python-Markdown 2.6 which adds a few new features
+and fixes various bugs. See the list of changes below for details.
+
+Python-Markdown version 2.6 supports Python versions 2.7, 3.2, 3.3, and 3.4.
+
+Backwards-incompatible Changes
+------------------------------
+
+* Both `safe_mode` and the associated `html_replacement_text` keywords are deprecated 
+  in version 2.6 and will raise a **`DeprecationWarning`**. The `safe_mode` and
+  `html_replacement_text` keywords will be ignored in version 2.7. The so-called
+  "safe mode" was never actually "safe" which has resulted in many people having a false 
+  sense of security when using it. As an alternative, the developers of Python-Markdown 
+  recommend that any untrusted content be passed through an HTML sanitizer (like [Bleach])
+  after being converted to HTML by markdown.
+
+    If your code previously looked like this:
+
+	    html = markdown.markdown(text, same_mode=True)
+
+	Then it is recommended that you change your code to read something like this:
+
+	    import bleach
+        html = bleach.clean(markdown.markdown(text))
+
+	If you are not interested in sanitizing untrusted text, but simply desire to escape
+	raw HTML, then that can be accomplished through an extension which removes HTML parsing:
+
+		from markdown.extensions import Extension
+
+		class EscapeHtml(Extension):
+			def extendMarkdown(self, md, md_globals):
+				del md.preprocessors['html_block']
+				del md.inlinePatterns['html']
+
+		html = markdown.markdown(text, extensions=[EscapeHtml()])
+
+	As the HTML would not be parsed with the above Extension, then the searializer will
+	escape the raw HTML, which is exactly what happens now when `safe_mode="escape"`.
+
+[Bleach]: http://bleach.readthedocs.org/
+
+* Positional arguments on the `markdown.Markdown()` are deprecated as are
+  all except the `text` argument on the `markdown.markdown()` wrapper function.
+  Using positional argument will raise a **`DeprecationWarning`** in 2.6 and an error
+  in version 2.7. Only keyword arguments should be used. For example, if your code
+  previosuly looked like this:
+
+         html = markdown.markdown(text, ['extra'])
+    
+	Then it is recommended that you change it to read something like this:
+
+	    html = markdown.markdown(text, extensions=['extra'])
+
+	!!! Note
+	    This change is being made as a result of deprecating `"safe_mode"` as the 
+		`safe_mode` argumnet was one of the positional arguments. When that argument 
+		is removed, the two arguments following it will no longer be at the correct 
+		position. It is recomended that you always use keywords when they are supported
+		for this reason.
+
+* In previous versions of Python-Markdown, the builtin extensions received
+  special status and did not require the full path to be provided. Additionaly,
+  third party extensions whose name started with "mdx_" received the same 
+  special treatment. This behavior is deprecated and will raise a
+  **`DeprecationWarning`** in version 2.6 and an error in 2.7. Ensure that you
+  always use the full path to your extensions. For example, if you previously
+  did the following:
+
+        markdown.markdown(text, extensions=['extra'])
+
+    You should change your code to the following:
+
+	    markdown.markdown(text, extensions=['markdown.extensions.extra'])
+
+    The same applies to the command line:
+
+        $ python -m markdown -x markdown.extensions.extra input.txt
+
+    See the [documentation](reference.html#extensions) for a full explaination
+    of the current behavior.
+
+* The previously documented method of appending the extension configs as 
+  a string to the extension name is deprecated and will raise a
+  **`DeprecationWarning`** in version 2.6 and an error in 2.7.
+  The [extension_configs](reference.html#extension_configs) keyword should 
+  be used instead. See the [documentation](reference.html#extension-configs) 
+  for a full explaination of the current behavior.
+
+What's New in Python-Markdown 2.6
+---------------------------------
+
+*   The [Meta-Data] Extension now includes optional support for [YAML] style
+    meta-data. By default, the YAML deliminators are recognized, however, the
+    actual data is parsed as previously.  This follows the syntax of
+    [MultiMarkdown], which inspired this extension.
+
+    Alternatively, if the `yaml` option is set, then the data is parsed as YAML.
+
+[MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata
+[Meta-Data]: extensions/meta_data.html
+[YAML]: http://yaml.org/
+
+*   The [TOC] Extension has been refactored. Significantly, the extension now
+    assigns the Table of Contents to the `toc` attrbibute of the Markdown class
+    regardless of whether a "marker" was found in the document. Third party
+    frameworks no longer need to insert a "marker," run the document through
+    Markdown, then extract the TOC from the document.
+    
+    Additionaly, the TOC Extension is now a "registered extension." Therefore,
+    when the `reset` method of the Markdown class is called, the `toc` attribute
+    on the Markdown class is cleared (set to an empty string).
+
+[TOC]: extensions/toc.html
+
+*   Test coverage has been improved including running [flake8]. While those changes
+    will not directly effect end users, the code is being better tested which will 
+    benefit everyone.
+
+[fake8]: http://flake8.readthedocs.org/en/latest/
+
+*   Various bug fixes have been made.  See the
+    [commit log](https://github.com/waylan/Python-Markdown/commits/master)
+    for a complete history of the changes.