Reformatted Release Notes for 2.6.

This format (using subheading rather than lists), allows for easy
linking to each individual section of the release notes. I think
we should sue this format going forward.

Also added an additional example to clarify the deprecation of the
special treatment of the 'mdx_' prefix for third party extensions.

1 files changed, 188 insertions, 154 deletions

diff --git a/docs/release-2.6.txt b/docs/release-2.6.txt
index 0a95780..f222d6c 100644
--- a/docs/release-2.6.txt
+++ b/docs/release-2.6.txt
@@ -15,144 +15,168 @@ Python-Markdown version 2.6 supports Python versions 2.7, 3.2, 3.3, and 3.4 as w
 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.
+### `safe_mode` Deprecated
 
-    If your code previously looked like this:
+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.
 
-        html = markdown.markdown(text, safe_mode=True)
+If your code previously looked like this:
 
-    Then it is recommended that you change your code to read something like this:
+    html = markdown.markdown(text, safe_mode=True)
 
-        import bleach
-        html = bleach.clean(markdown.markdown(text))
+Then it is recommended that you change your code to read something like this:
 
-    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:
+    import bleach
+    html = bleach.clean(markdown.markdown(text))
 
-        from markdown.extensions import Extension
+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:
 
-        class EscapeHtml(Extension):
-            def extendMarkdown(self, md, md_globals):
-            del md.preprocessors['html_block']
-            del md.inlinePatterns['html']
+    from markdown.extensions import Extension
 
-        html = markdown.markdown(text, extensions=[EscapeHtml()])
+    class EscapeHtml(Extension):
+        def extendMarkdown(self, md, md_globals):
+        del md.preprocessors['html_block']
+        del md.inlinePatterns['html']
 
-    As the HTML would not be parsed with the above Extension, then the serializer will
-    escape the raw HTML, which is exactly what happens now when `safe_mode="escape"`.
+    html = markdown.markdown(text, extensions=[EscapeHtml()])
+
+As the HTML would not be parsed with the above Extension, then the serializer 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()` class are deprecated as are
-    all except the `text` argument on the `markdown.markdown()` wrapper function.
-    Using positional arguments 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
-    previously looked like this:
+### Positional Arguments Deprecated
+
+Positional arguments on the `markdown.Markdown()` class are deprecated as are
+all except the `text` argument on the `markdown.markdown()` wrapper function.
+Using positional arguments 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
+previously looked like this:
+
+    html = markdown.markdown(text, [SomeExtension()])
+
+Then it is recommended that you change it to read something like this:
+
+    html = markdown.markdown(text, extensions=[SomeExtension()])
+
+!!! Note
+    This change is being made as a result of deprecating `"safe_mode"` as the 
+    `safe_mode` argument 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 recommended that you always use keywords when they are supported
+    for this reason.
+
+### "Shortened" Extension Names Deprecated
+
+In previous versions of Python-Markdown, the built-in extensions received
+special status and did not require the full path to be provided. Additionally,
+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'])
 
-        html = markdown.markdown(text, [SomeExtension()])
-    
-    Then it is recommended that you change it to read something like this:
+You should change your code to the following:
 
-        html = markdown.markdown(text, extensions=[SomeExtension()])
+    markdown.markdown(text, extensions=['markdown.extensions.extra'])
 
-    !!! Note
-        This change is being made as a result of deprecating `"safe_mode"` as the 
-        `safe_mode` argument 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 recommended that you always use keywords when they are supported
-        for this reason.
+The same applies to the command line:
 
-* In previous versions of Python-Markdown, the built-in extensions received
-  special status and did not require the full path to be provided. Additionally,
-  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:
+    $ python -m markdown -x markdown.extensions.extra input.txt
 
-        markdown.markdown(text, extensions=['extra'])
+Similarly, if you have used a third party extension (eg: `mdx_math`), previously
+you might have called it like this:
 
-    You should change your code to the following:
+    markdown.markdown(text, extensions=['math'])
 
-        markdown.markdown(text, extensions=['markdown.extensions.extra'])
+As the `"mdx"` prefix will no longer be appended, you will need to change your code
+as follows (assuming the file `mdx_math.py` is installed at the root of your PYTHONPATH):
 
-    The same applies to the command line:
+    markdown.markdown(text, extensions=['mdx_math'])
 
-        $ python -m markdown -x markdown.extensions.extra input.txt
+Extension authors will want to update their documentation to reflect the new behavior.
 
-    See the [documentation](reference.html#extensions) for a full explanation
-    of the current behavior.
+See the [documentation](reference.html#extensions) for a full explanation
+of the current behavior.
 
-*   The previously documented method of appending the extension configuration options 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 explanation of the current behavior.
+### Extension Configs as Part of Extension Name Deprecated
 
-*   The [HeaderId][hid] Extension is pending deprecation and will raise a
-    **`PendingDeprecationWarning`** in version 2.6. The extension will be
-    deprecated in version 2.7 and raise an error in version 2.8. Use the
-    [Table of Contents][TOC] Extension instead, which offers most of the
-    features of the HeaderId Extension and more (support for meta data is missing).
-  
-    Extension authors who have been using the `slugify` and `unique` functions
-    defined in the HeaderId Extension should note that those functions are now
-    defined in the Table of Contents extension and should adjust their import
-    statements accordingly (`from markdown.extensions.toc import slugify, unique`).
+The previously documented method of appending the extension configuration options 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 explanation of the current behavior.
+
+### HeaderId Extension Pending Deprecation
+
+The [HeaderId][hid] Extension is pending deprecation and will raise a
+**`PendingDeprecationWarning`** in version 2.6. The extension will be
+deprecated in version 2.7 and raise an error in version 2.8. Use the
+[Table of Contents][TOC] Extension instead, which offers most of the
+features of the HeaderId Extension and more (support for meta data is missing).
+
+Extension authors who have been using the `slugify` and `unique` functions
+defined in the HeaderId Extension should note that those functions are now
+defined in the Table of Contents extension and should adjust their import
+statements accordingly (`from markdown.extensions.toc import slugify, unique`).
 
 [hid]: extensions/header_id.html
 
-*   Positional arguments and the `configs` keyword on the `markdown.extension.Extension` class
-    (and its subclasses) are deprecated. Each individual configuration option should be passed
-    to the class as a keyword/value pair. For example. one might have previously initiated
-    an extension subclass like this:
-
-        ext = SomeExtension(configs={'somekey': 'somevalue'})
-
-    That code should be updated to pass in the options directly:
-    
-        ext = SomeExtension(somekey='somevalue')
-    
-    Extension authors will want to note that this affects the `makeExtension` function as well.
-    Previously it was common for the function to be defined as follows:
-    
-        def makeExtension(configs=None):
-            return SomeExtension(configs=configs)
-
-    Extension authors will want to update their code to the following instead:
-
-        def makeExtension(**kwargs):
-            return SomeExtension(**kwargs)
-
-    Failing to do so will result in a **`DeprecationWarning`** and will raise an error in the next
-    release. See the [Extension API][mext] documentation for more information.
-
-    In the event that an `markdown.extension.Extension` subclass overrides the `__init__` method
-    and implements its own configuration handling, then the above may not apply. However, it is
-    recommended that the subclass still calls the parent `__init__` method to handle configuration
-    options like so:
-    
-        class SomeExtension(markdown.extension.Extension):
-            def __init__(**kwargs):
-                # Do pre-config stuff here
-                # Set config defaults
-                self.config = {
-                    'option1' : ['value1', 'description1'],
-                    'option2' : ['value2', 'description2']
-                }
-                # Set user defined configs
-                super(MyExtension, self).__init__(**kwargs)
-                # Do post-config stuff here
-
-    Note the call to `super` to get the benefits of configuration handling from the parent class.
-    See the [documentation][config] for more information.
+### `configs` Keyword Deprecated
+
+Positional arguments and the `configs` keyword on the `markdown.extension.Extension` class
+(and its subclasses) are deprecated. Each individual configuration option should be passed
+to the class as a keyword/value pair. For example. one might have previously initiated
+an extension subclass like this:
+
+    ext = SomeExtension(configs={'somekey': 'somevalue'})
+
+That code should be updated to pass in the options directly:
+
+    ext = SomeExtension(somekey='somevalue')
+
+Extension authors will want to note that this affects the `makeExtension` function as well.
+Previously it was common for the function to be defined as follows:
+
+    def makeExtension(configs=None):
+        return SomeExtension(configs=configs)
+
+Extension authors will want to update their code to the following instead:
+
+    def makeExtension(**kwargs):
+        return SomeExtension(**kwargs)
+
+Failing to do so will result in a **`DeprecationWarning`** and will raise an error in the next
+release. See the [Extension API][mext] documentation for more information.
+
+In the event that an `markdown.extension.Extension` subclass overrides the `__init__` method
+and implements its own configuration handling, then the above may not apply. However, it is
+recommended that the subclass still calls the parent `__init__` method to handle configuration
+options like so:
+
+    class SomeExtension(markdown.extension.Extension):
+        def __init__(**kwargs):
+            # Do pre-config stuff here
+            # Set config defaults
+            self.config = {
+                'option1' : ['value1', 'description1'],
+                'option2' : ['value2', 'description2']
+            }
+            # Set user defined configs
+            super(MyExtension, self).__init__(**kwargs)
+            # Do post-config stuff here
+
+Note the call to `super` to get the benefits of configuration handling from the parent class.
+See the [documentation][config] for more information.
 
 [config]: extensions/api.html#configsettings
 [mext]: extensions/api.html#makeextension
@@ -160,66 +184,76 @@ Backwards-incompatible Changes
 What's New in Python-Markdown 2.6
 ---------------------------------
 
-*   Official support for [PyPy] has been added. While Python-Markdown has most likely
+### Official Support for PyPy
+
+Official support for [PyPy] has been added. While Python-Markdown has most likely
 worked on PyPy for some time, it is now officially supported and tested on PyPy.
 
 [PyPy]: http://pypy.org/
 
-*   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.
+### YAML Style Meta-Data
+
+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.
+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 [Table of Contents][TOC] Extension has been refactored and some new features
-    have been added.  See the documentation for a full explanation of each feature
-    listed below:
-
-      * The extension now assigns the Table of Contents to the `toc` attribute 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 Table of Contents from the document.
-    
-      * The Table of Contents 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).
-  
-      * When the `marker` configuration option is set to an empty string, the parser completely
-        skips the process of searching the document for markers. This should save parsing
-        time when the Table of Contents Extension is being used only to assign ids to headers.
-
-      * A `separator` configuration option has been added allowing users to override the
-        separator character used by the slugify function.
-  
-      * A `baselevel` configuration option has been added allowing users to set the base level
-        of headers in their documents (h1-h6). This allows the header levels to be
-        automatically adjusted to fit within the hierarchy of an HTML template.
+### TOC Extension Refactored
+
+The [Table of Contents][TOC] Extension has been refactored and some new features
+have been added.  See the documentation for a full explanation of each feature
+listed below:
+
+*   The extension now assigns the Table of Contents to the `toc` attribute 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 Table of Contents from the document.
+
+*   The Table of Contents 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).
+
+*   When the `marker` configuration option is set to an empty string, the parser completely
+    skips the process of searching the document for markers. This should save parsing
+    time when the Table of Contents Extension is being used only to assign ids to headers.
+
+*   A `separator` configuration option has been added allowing users to override the
+    separator character used by the slugify function.
+
+*   A `baselevel` configuration option has been added allowing users to set the base level
+    of headers in their documents (h1-h6). This allows the header levels to be
+    automatically adjusted to fit within the hierarchy of an HTML template.
 
 [TOC]: extensions/toc.html
 
-*   The [CodeHilite][ch] Extension has gained a new configuration option: `use_pygments`.
-    The option is `True` by default, however, it allows one to turn off Pygments code
-    highlighting (set to `False`) while preserving the language detection features of
-    the extension. Note that Pygments language guessing is not used as that would 'use
-    Pygments'. If a language is defined for a code block, it will be assigned to the
-    `<code>` tag as a class in the manner suggested by the [HTML5 spec][spec]
-    (alternate output will not be entertained) and could potentially be used by a JavaScript
-    library in the browser to highlight the code block.
+### Pygments can now be disabled
+
+The [CodeHilite][ch] Extension has gained a new configuration option: `use_pygments`.
+The option is `True` by default, however, it allows one to turn off Pygments code
+highlighting (set to `False`) while preserving the language detection features of
+the extension. Note that Pygments language guessing is not used as that would 'use
+Pygments'. If a language is defined for a code block, it will be assigned to the 
+`<code>` tag as a class in the manner suggested by the [HTML5 spec][spec]
+(alternate output will not be entertained) and could potentially be used by a JavaScript
+library in the browser to highlight the code block.
 
 [ch]: extensions/code_hilite.html
 [spec]: http://www.w3.org/TR/html5/text-level-semantics.html#the-code-element
 
-*   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.
+### Miscellaneous
+
+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.
 
 [flake8]: 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.
+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.