/usr/share/doc/python-markdown-doc/docs/release-2.6.html is in python-markdown-doc 2.6.9-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 | <!DOCTYPE html>
<html>
<head>
<meta charset=utf-8>
<title>Release Notes for v2.6 — Python Markdown</title>
<link rel="stylesheet" href="default.css" type="text/css">
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="siteindex.html" title="General Index">index</a></li>
<li class="right">
<a href="release-2.5.html" title="Release Notes for v2.5"
accesskey="N">next</a> |</li>
<li class="right">
<a href="change_log.html" title="Change Log"
accesskey="P">previous</a> |</li>
<li><img src="py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="index.html">Python Markdown v2.6.9 documentation</a> »</li>
<li><a href="release-2.6.html">Release Notes for v2.6</a> »</li>
</ul>
</div> <!-- .related -->
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<h1 id="python-markdown-26-release-notes">Python-Markdown 2.6 Release Notes<a class="headerlink" href="#python-markdown-26-release-notes" title="Permanent link">¶</a></h1>
<p>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.</p>
<p>Python-Markdown version 2.6 supports Python versions 2.7, 3.2, 3.3, and 3.4 as well as PyPy.</p>
<h2 id="backwards-incompatible-changes">Backwards-incompatible Changes<a class="headerlink" href="#backwards-incompatible-changes" title="Permanent link">¶</a></h2>
<h3 id="safe_mode-deprecated"><code>safe_mode</code> Deprecated<a class="headerlink" href="#safe_mode-deprecated" title="Permanent link">¶</a></h3>
<p>Both <code>safe_mode</code> and the associated <code>html_replacement_text</code> keywords are deprecated
in version 2.6 and will raise a <strong><code>DeprecationWarning</code></strong>. The <code>safe_mode</code> and
<code>html_replacement_text</code> 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 <a href="https://bleach.readthedocs.io/">Bleach</a>)
after being converted to HTML by markdown.</p>
<p>If your code previously looked like this:</p>
<pre><code>html = markdown.markdown(text, safe_mode=True)
</code></pre>
<p>Then it is recommended that you change your code to read something like this:</p>
<pre><code>import bleach
html = bleach.clean(markdown.markdown(text))
</code></pre>
<p>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:</p>
<pre><code>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()])
</code></pre>
<p>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 <code>safe_mode="escape"</code>.</p>
<h3 id="positional-arguments-deprecated">Positional Arguments Deprecated<a class="headerlink" href="#positional-arguments-deprecated" title="Permanent link">¶</a></h3>
<p>Positional arguments on the <code>markdown.Markdown()</code> class are deprecated as are
all except the <code>text</code> argument on the <code>markdown.markdown()</code> wrapper function.
Using positional arguments will raise a <strong><code>DeprecationWarning</code></strong> 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:</p>
<pre><code>html = markdown.markdown(text, [SomeExtension()])
</code></pre>
<p>Then it is recommended that you change it to read something like this:</p>
<pre><code>html = markdown.markdown(text, extensions=[SomeExtension()])
</code></pre>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This change is being made as a result of deprecating <code>"safe_mode"</code> as the
<code>safe_mode</code> 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.</p>
</div>
<h3 id="shortened-extension-names-deprecated">“Shortened” Extension Names Deprecated<a class="headerlink" href="#shortened-extension-names-deprecated" title="Permanent link">¶</a></h3>
<p>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 <code>"mdx_"</code> received the same
special treatment. This behavior is deprecated and will raise a
<strong><code>DeprecationWarning</code></strong> 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:</p>
<pre><code>markdown.markdown(text, extensions=['extra'])
</code></pre>
<p>You should change your code to the following:</p>
<pre><code>markdown.markdown(text, extensions=['markdown.extensions.extra'])
</code></pre>
<p>The same applies to the command line:</p>
<pre><code>$ python -m markdown -x markdown.extensions.extra input.txt
</code></pre>
<p>Similarly, if you have used a third party extension (for example <code>mdx_math</code>), previously
you might have called it like this:</p>
<pre><code>markdown.markdown(text, extensions=['math'])
</code></pre>
<p>As the <code>"mdx"</code> prefix will no longer be appended, you will need to change your code
as follows (assuming the file <code>mdx_math.py</code> is installed at the root of your PYTHONPATH):</p>
<pre><code>markdown.markdown(text, extensions=['mdx_math'])
</code></pre>
<p>Extension authors will want to update their documentation to reflect the new behavior.</p>
<p>See the <a href="reference.html#extensions">documentation</a> for a full explanation
of the current behavior.</p>
<h3 id="extension-configuration-as-part-of-extension-name-deprecated">Extension Configuration as Part of Extension Name Deprecated<a class="headerlink" href="#extension-configuration-as-part-of-extension-name-deprecated" title="Permanent link">¶</a></h3>
<p>The previously documented method of appending the extension configuration options as
a string to the extension name is deprecated and will raise a
<strong><code>DeprecationWarning</code></strong> in version 2.6 and an error in 2.7.
The <a href="reference.html#extension_configs"><code>extension_configs</code></a> keyword should
be used instead. See the <a href="reference.html#extension-configs">documentation</a>
for a full explanation of the current behavior.</p>
<h3 id="headerid-extension-pending-deprecation">HeaderId Extension Pending Deprecation<a class="headerlink" href="#headerid-extension-pending-deprecation" title="Permanent link">¶</a></h3>
<p>The <a href="extensions/header_id.html">HeaderId</a> Extension is pending deprecation and will raise a
<strong><code>PendingDeprecationWarning</code></strong> in version 2.6. The extension will be
deprecated in version 2.7 and raise an error in version 2.8. Use the
<a href="extensions/toc.html">Table of Contents</a> Extension instead, which offers most of the
features of the HeaderId Extension and more (support for meta data is missing).</p>
<p>Extension authors who have been using the <code>slugify</code> and <code>unique</code> 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 (<code>from markdown.extensions.toc import slugify, unique</code>).</p>
<h3 id="the-configs-keyword-is-deprecated">The <code>configs</code> Keyword is Deprecated<a class="headerlink" href="#the-configs-keyword-is-deprecated" title="Permanent link">¶</a></h3>
<p>Positional arguments and the <code>configs</code> keyword on the <code>markdown.extension.Extension</code> 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:</p>
<pre><code>ext = SomeExtension(configs={'somekey': 'somevalue'})
</code></pre>
<p>That code should be updated to pass in the options directly:</p>
<pre><code>ext = SomeExtension(somekey='somevalue')
</code></pre>
<p>Extension authors will want to note that this affects the <code>makeExtension</code> function as well.
Previously it was common for the function to be defined as follows:</p>
<pre><code>def makeExtension(configs=None):
return SomeExtension(configs=configs)
</code></pre>
<p>Extension authors will want to update their code to the following instead:</p>
<pre><code>def makeExtension(**kwargs):
return SomeExtension(**kwargs)
</code></pre>
<p>Failing to do so will result in a <strong><code>DeprecationWarning</code></strong> and will raise an error in the next
release. See the <a href="extensions/api.html#makeextension">Extension API</a> documentation for more information.</p>
<p>In the event that an <code>markdown.extension.Extension</code> subclass overrides the <code>__init__</code> method
and implements its own configuration handling, then the above may not apply. However, it is
recommended that the subclass still calls the parent <code>__init__</code> method to handle configuration
options like so:</p>
<pre><code>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
</code></pre>
<p>Note the call to <code>super</code> to get the benefits of configuration handling from the parent class.
See the <a href="extensions/api.html#configsettings">documentation</a> for more information.</p>
<h2 id="whats-new-in-python-markdown-26">What’s New in Python-Markdown 2.6<a class="headerlink" href="#whats-new-in-python-markdown-26" title="Permanent link">¶</a></h2>
<h3 id="official-support-for-pypy">Official Support for PyPy<a class="headerlink" href="#official-support-for-pypy" title="Permanent link">¶</a></h3>
<p>Official support for <a href="http://pypy.org/">PyPy</a> has been added. While Python-Markdown has most likely
worked on PyPy for some time, it is now officially supported and tested on PyPy.</p>
<h3 id="yaml-style-meta-data">YAML Style Meta-Data<a class="headerlink" href="#yaml-style-meta-data" title="Permanent link">¶</a></h3>
<p>The <a href="extensions/meta_data.html">Meta-Data</a> Extension now includes optional support for <a href="http://yaml.org/">YAML</a> style
meta-data. By default, the YAML deliminators are recognized, however, the
actual data is parsed as previously. This follows the syntax of
<a href="http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata">MultiMarkdown</a>, which inspired this extension.</p>
<p><del>Alternatively, if the <code>yaml</code> option is set, then the data is parsed as YAML.</del>
<ins>As the <code>yaml</code> option was buggy, it was removed in 2.6.1. It is suggested that a third
party extension be used if you want true YAML support. See <a href="https://github.com/Python-Markdown/markdown/issues/390">Issue #390</a> for a full
explanation.</ins></p>
<h3 id="table-of-contents-extension-refactored">Table of Contents Extension Refactored<a class="headerlink" href="#table-of-contents-extension-refactored" title="Permanent link">¶</a></h3>
<p>The <a href="extensions/toc.html">Table of Contents</a> Extension has been refactored and some new features
have been added. See the documentation for a full explanation of each feature
listed below:</p>
<ul>
<li>
<p>The extension now assigns the Table of Contents to the <code>toc</code> 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.</p>
</li>
<li>
<p>The Table of Contents Extension is now a “registered extension.” Therefore, when the <code>reset</code>
method of the Markdown class is called, the <code>toc</code> attribute on the Markdown
class is cleared (set to an empty string).</p>
</li>
<li>
<p>When the <code>marker</code> 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.</p>
</li>
<li>
<p>A <code>separator</code> configuration option has been added allowing users to override the
separator character used by the slugify function.</p>
</li>
<li>
<p>A <code>baselevel</code> 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.</p>
</li>
</ul>
<h3 id="pygments-can-now-be-disabled">Pygments can now be disabled<a class="headerlink" href="#pygments-can-now-be-disabled" title="Permanent link">¶</a></h3>
<p>The <a href="extensions/code_hilite.html">CodeHilite</a> Extension has gained a new configuration option: <code>use_pygments</code>.
The option is <code>True</code> by default, however, it allows one to turn off Pygments code
highlighting (set to <code>False</code>) 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><code></code> tag as a class in the manner suggested by the <a href="http://www.w3.org/TR/html5/text-level-semantics.html#the-code-element">HTML5 spec</a>
(alternate output will not be entertained) and could potentially be used by a JavaScript
library in the browser to highlight the code block.</p>
<h3 id="miscellaneous">Miscellaneous<a class="headerlink" href="#miscellaneous" title="Permanent link">¶</a></h3>
<p>Test coverage has been improved including running <a href="https://flake8.readthedocs.io/en/latest/">flake8</a>. While those changes
will not directly effect end users, the code is being better tested which will
benefit everyone.</p>
<p>Various bug fixes have been made. See the
<a href="https://github.com/Python-Markdown/markdown/commits/master">commit log</a>
for a complete history of the changes.</p>
</div> <!-- .body -->
</div> <!-- .bodywrapper -->
</div> <!-- .documentwrapper -->
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3>Table Of Contents</h3>
<div class="toc">
<ul>
<li><a href="#python-markdown-26-release-notes">Python-Markdown 2.6 Release Notes</a><ul>
<li><a href="#backwards-incompatible-changes">Backwards-incompatible Changes</a><ul>
<li><a href="#safe_mode-deprecated">safe_mode Deprecated</a></li>
<li><a href="#positional-arguments-deprecated">Positional Arguments Deprecated</a></li>
<li><a href="#shortened-extension-names-deprecated">"Shortened" Extension Names Deprecated</a></li>
<li><a href="#extension-configuration-as-part-of-extension-name-deprecated">Extension Configuration as Part of Extension Name Deprecated</a></li>
<li><a href="#headerid-extension-pending-deprecation">HeaderId Extension Pending Deprecation</a></li>
<li><a href="#the-configs-keyword-is-deprecated">The configs Keyword is Deprecated</a></li>
</ul>
</li>
<li><a href="#whats-new-in-python-markdown-26">What's New in Python-Markdown 2.6</a><ul>
<li><a href="#official-support-for-pypy">Official Support for PyPy</a></li>
<li><a href="#yaml-style-meta-data">YAML Style Meta-Data</a></li>
<li><a href="#table-of-contents-extension-refactored">Table of Contents Extension Refactored</a></li>
<li><a href="#pygments-can-now-be-disabled">Pygments can now be disabled</a></li>
<li><a href="#miscellaneous">Miscellaneous</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<h4>Previous topic</h4>
<p class="topless"><a href="change_log.html"
title="previous chapter">Change Log</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="release-2.5.html"
title="next chapter">Release Notes for v2.5</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="https://github.com/Python-Markdown/markdown/issues"
>Report a Bug</a></li>
<li><a href="release-2.6.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div> <!-- .sphinxsidebarwrapper -->
</div> <!-- .sphinxsidebar -->
<div class="clearer"></div>
</div> <!-- .document -->
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="siteindex.html" title="General Index">index</a></li>
<li class="right">
<a href="release-2.5.html" title="Release Notes for v2.5"
accesskey="N">next</a> |</li>
<li class="right">
<a href="change_log.html" title="Change Log"
accesskey="P">previous</a> |</li>
<li><img src="py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="index.html">Python Markdown v2.6.9 documentation</a> »</li>
<li><a href="release-2.6.html">Release Notes for v2.6</a> »</li>
</ul>
</div> <!-- .related -->
<div class="footer">© 2010-2012 Python Markdown Project</div>
</body>
</html>
|