This file is indexed.

/usr/share/doc/python-markdown-doc/docs/reference.html is in python-markdown-doc 2.4-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
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
<!DOCTYPE html>
<html>
<head>
<meta charset=utf-8>
<title>Library Reference &#8212; 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="cli.html" title="Command Line"
         accesskey="N">next</a> |</li>
    <li class="right">
      <a href="install.html" title="Installation"
         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.4 documentation</a> &raquo;</li>
    <li><a href="reference.html">Library Reference</a> &raquo;</li>
  </ul>
</div> <!-- .related -->

<div class="document">
  <div class="documentwrapper">
    <div class="bodywrapper">
      <div class="body">
<h1 id="using-markdown-as-a-python-library">Using Markdown as a Python Library<a class="headerlink" href="#using-markdown-as-a-python-library" title="Permanent link">&para;</a></h1>
<p>First and foremost, Python-Markdown is intended to be a python library module
used by various projects to convert Markdown syntax into HTML.</p>
<h2 id="the-basics">The Basics<a class="headerlink" href="#the-basics" title="Permanent link">&para;</a></h2>
<p>To use markdown as a module:</p>
<pre><code>import markdown
html = markdown.markdown(your_text_string)
</code></pre>
<h2 id="the-details">The Details<a class="headerlink" href="#the-details" title="Permanent link">&para;</a></h2>
<p>Python-Markdown provides two public functions (<a href="#markdown"><code>markdown.markdown</code></a>
and <a href="#markdownFromFile"><code>markdown.markdownFromFile</code></a>) both of which wrap the 
public class <a href="#Markdown"><code>markdown.Markdown</code></a>. If you&rsquo;re processing one 
document at a time, the functions will serve your needs. However, if you need 
to process multiple documents, it may be advantageous to create a single 
instance of the <code>markdown.Markdown</code> class and pass multiple documents through 
it.</p>
<h3 id="markdown"><code>markdown.markdown (text [, **kwargs])</code><a class="headerlink" href="#markdown" title="Permanent link">&para;</a></h3>
<p>The following options are available on the <code>markdown.markdown</code> function:</p>
<ul>
<li>
<p><strong id="text"><code>text</code></strong> (required): The source unicode string.</p>
<div class="admonition note">
<p class="admonition-title">Important</p>
<p>Python-Markdown expects <strong>Unicode</strong> as input (although
some simple ASCII strings <em>may</em> work) and returns output as Unicode.
Do not pass encoded strings to it! If your input is encoded, (e.g. as 
UTF-8), it is your responsibility to decode it.  For example:</p>
<pre><code>input_file = codecs.open("some_file.txt", mode="r", encoding="utf-8")
text = input_file.read()
html = markdown.markdown(text)
</code></pre>
<p>If you want to write the output to disk, you <em>must</em> encode it yourself:</p>
<pre><code>output_file = codecs.open("some_file.html", "w", 
                          encoding="utf-8", 
                          errors="xmlcharrefreplace"
)
output_file.write(html)
</code></pre>
</div>
</li>
<li>
<p><strong id="extensions"><code>extensions</code></strong>: A list of extensions.</p>
<p>Python-Markdown provides an <a href="extensions/api.html">API</a> for third parties to
write extensions to the parser adding their own additions or changes to the
syntax. A few commonly used extensions are shipped with the markdown 
library. See the <a href="extensions/index.html">extension documentation</a> for a 
list of available extensions.</p>
<p>The list of extensions may contain instances of extensions and/or strings 
of extension names. </p>
<pre><code>extensions=[MyExtension(), 'path.to.my.ext', 'extra']
</code></pre>
<p>When passing in extension instances, each class instance must be a subclass
of <code>markdown.extensions.Extension</code> and any configuration options should be 
defined when initiating the class instance rather than using the 
<a href="#extension_configs">extension_configs</a> keyword. For example:</p>
<pre><code>from markdown.extensions import Extension
class MyExtension(Extension):
    # define your extension here...

markdown.markdown(text, extensions=[MyExtension(configs={'option': 'value'}))
</code></pre>
<p>If an extension name is provided as a string, the extension must be 
importable as a python module on your PYTHONPATH. Python&rsquo;s dot notation is 
supported. Therefore, to import the &lsquo;extra&rsquo; extension, one could do 
<code>extensions=['markdown.extensions.extra']</code> However, if no dots are provided 
in the string (<code>extensions=['extra']</code>) Markdown will first look for the 
module <code>markdown.extensions.extra</code> (the built-in extension), then a module 
named <code>mdx_extra</code> (&lsquo;mdx_&rsquo; will be appended to the beginning of the string) 
at the root of your PYTHONPATH. </p>
<p>When loading an extension by name (as a sting), you may either pass in
configuration settings to the extension using the 
<a href="#extension_configs">extension_configs</a> keyword or by appending the 
settings to the name in the following format:</p>
<pre><code>extensions=['name(option1=value,option2=value)']
</code></pre>
<p>Note that there are no quotes or whitespace in the above format, which 
severely limits how it can be used. For more complex settings, it is 
suggested that the <a href="#extension_configs">extension_configs</a> keyword
be used or an instance of a class be passed in.</p>
<div class="admonition seealso">
<p class="admonition-title">See Also</p>
<p>See the documentation of the <a href="extensions/api.html">Extension API</a> for 
assistance in creating extensions.</p>
</div>
</li>
<li>
<p><strong id="extension_configs"><code>extension_configs</code></strong>: A dictionary of
  configuration settings for extensions.</p>
<p>Any configuration settings will only be passed to extensions loaded by name 
(as a string). When loading extensions as class instances, pass the 
configuration settings directly to the class when initializing it. </p>
<p>The dictionary of configuration settings must be in the following format:</p>
<pre><code>extension_configs = {'extension_name_1':
                       [
                          ('option_1', 'value_1'),
                          ('option_2', 'value_2')
                       ],
                     'extension_name_2':
                       [
                          ('option_1', 'value_1')
                       ]
                    }
</code></pre>
<p>See the documentation specific to the extension you are using for help in 
specifying configuration settings for that extension.</p>
</li>
<li>
<p><strong id="output_format"><code>output_format</code></strong>: Format of output. </p>
<p>Supported formats are:</p>
<ul>
<li><code>"xhtml1"</code>: Outputs XHTML 1.x. <strong>Default</strong>.</li>
<li><code>"xhtml5"</code>: Outputs XHTML style tags of HTML 5</li>
<li><code>"xhtml"</code>: Outputs latest supported version of XHTML (currently XHTML 1.1).</li>
<li><code>"html4"</code>: Outputs HTML 4</li>
<li><code>"html5"</code>: Outputs HTML style tags of HTML 5</li>
<li><code>"html"</code>: Outputs latest supported version of HTML (currently HTML 4).</li>
</ul>
<p>The values can be in either lowercase or uppercase.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>It is suggested that the more specific formats (&ldquo;xhtml1&rdquo;, &ldquo;html5&rdquo;, &amp; 
&ldquo;html4&rdquo;) be used as the more general formats (&ldquo;xhtml&rdquo; or &ldquo;html&rdquo;) may 
change in the future if it makes sense at that time. </p>
</div>
</li>
<li>
<p><strong id="safe_mode"><code>safe_mode</code></strong>: Disallow raw html.</p>
<p>If you are using Markdown on a web system which will transform text 
provided by untrusted users, you may want to use the &ldquo;safe_mode&rdquo; 
option which ensures that the user&rsquo;s HTML tags are either replaced, 
removed or escaped. (They can still create links using Markdown syntax.)</p>
<p>The following values are accepted:</p>
<ul>
<li>
<p><code>False</code> (Default): Raw HTML is passed through unaltered.</p>
</li>
<li>
<p><code>replace</code>: Replace all HTML blocks with the text assigned to 
  <code>html_replacement_text</code> To maintain backward compatibility, setting 
  <code>safe_mode=True</code> will have the same effect as <code>safe_mode='replace'</code>.   </p>
<p>To replace raw HTML with something other than the default, do:</p>
<pre><code>md = markdown.Markdown(safe_mode='replace', 
                   html_replacement_text='--RAW HTML NOT ALLOWED--')
</code></pre>
</li>
<li>
<p><code>remove</code>: All raw HTML will be completely stripped from the text with
  no warning to the author.</p>
</li>
<li>
<p><code>escape</code>: All raw HTML will be escaped and included in the document.</p>
<p>For example, the following source:</p>
<pre><code>Foo &lt;b&gt;bar&lt;/b&gt;.
</code></pre>
<p>Will result in the following HTML:</p>
<pre><code>&lt;p&gt;Foo &amp;lt;b&amp;gt;bar&amp;lt;/b&amp;gt;.&lt;/p&gt;
</code></pre>
</li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>&ldquo;safe_mode&rdquo; also alters the default value for the 
<a href="#enable_attributes"><code>enable_attributes</code></a> option.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See Also</p>
<p>HTML sanitizers (like <a href="https://github.com/jsocol/bleach">Bleach</a>) may provide a better solution for 
dealing with markdown text submitted by untrusted users. That way, 
both the HTML generated by Markdown and user submited raw HTML are 
fully sanitized.</p>
<pre><code>import markdown
import bleach
html = bleach.clean(markdown.markdown(evil_text))
</code></pre>
</div>
</li>
<li>
<p><strong id="html_replacement_text"><code>html_replacement_text</code></strong>: Text used when 
  safe_mode is set to <code>replace</code>. Defaults to <code>[HTML_REMOVED]</code>.</p>
</li>
<li>
<p><strong id="tab_length"><code>tab_length</code></strong>: Length of tabs in the source. Default: 4</p>
</li>
<li>
<p><strong id="enable_attributes"><code>enable_attributes</code></strong>: Enable the conversion of 
  attributes. Defaults to <code>True</code>, unless <a href="#safe_mode"><code>safe_mode</code></a> is enabled, 
  in which case the default is <code>False</code>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><code>safe_mode</code> only overrides the default. If <code>enable_attributes</code> 
is explicitly set, the explicit value is used regardless of <code>safe_mode</code>.
However, this could potentially allow an untrusted user to inject
JavaScript into your documents.</p>
</div>
</li>
<li>
<p><strong id="smart_emphasis"><code>smart_emphasis</code></strong>: Treat <code>_connected_words_</code> 
  intelligently Default: True</p>
</li>
<li>
<p><strong id="lazy_ol"><code>lazy_ol</code></strong>: Ignore number of first item of ordered lists. 
  Default: True</p>
<p>Given the following list:</p>
<pre><code>4. Apples
5. Oranges
6. Pears
</code></pre>
<p>By default markdown will ignore the fact the the first line started 
with item number &ldquo;4&rdquo; and the HTML list will start with a number &ldquo;1&rdquo;.
If <code>lazy_ol</code> is set to <code>False</code>, then markdown will output the following
HTML:</p>
<pre><code>&lt;ol&gt;
  &lt;li start="4"&gt;Apples&lt;/li&gt;
  &lt;li&gt;Oranges&lt;/li&gt;
  &lt;li&gt;Pears&lt;/li&gt;
&lt;/ol&gt;
</code></pre>
</li>
</ul>
<h3 id="markdownFromFile"><code>markdown.markdownFromFile (**kwargs)</code><a class="headerlink" href="#markdownFromFile" title="Permanent link">&para;</a></h3>
<p>With a few exceptions, <code>markdown.markdownFromFile</code> accepts the same options as 
<code>markdown.markdown</code>. It does <strong>not</strong> accept a <code>text</code> (or Unicode) string. 
Instead, it accepts the following required options:</p>
<ul>
<li>
<p><strong id="input"><code>input</code></strong> (required): The source text file.</p>
<p><code>input</code> may be set to one of three options:</p>
<ul>
<li>a string which contains a path to a readable file on the file system,</li>
<li>a readable file-like object,</li>
<li>or <code>None</code> (default) which will read from <code>stdin</code>.</li>
</ul>
</li>
<li>
<p><strong id="output"><code>output</code></strong>: The target which output is written to.</p>
<p><code>output</code> may be set to one of three options:</p>
<ul>
<li>a string which contains a path to a writable file on the file system,</li>
<li>a writable file-like object,</li>
<li>or <code>None</code> (default) which will write to <code>stdout</code>.</li>
</ul>
</li>
<li>
<p><strong id="encoding"><code>encoding</code></strong>: The encoding of the source text file. Defaults 
  to &ldquo;utf-8&rdquo;. The same encoding will always be used for input and output. 
  The &lsquo;xmlcharrefreplace&rsquo; error handler is used when encoding the output.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This is the only place that decoding and encoding of unicode
takes place in Python-Markdown. If this rather naive solution does not
meet your specific needs, it is suggested that you write your own code
to handle your encoding/decoding needs.</p>
</div>
</li>
</ul>
<h3 id="Markdown"><code>markdown.Markdown ([**kwargs])</code><a class="headerlink" href="#Markdown" title="Permanent link">&para;</a></h3>
<p>The same options are available when initializing the <code>markdown.Markdown</code> class
as on the <a href="#markdown"><code>markdown.markdown</code></a> function, except that the class does
<strong>not</strong> accept a source text string on initialization. Rather, the source text
string must be passed to one of two instance methods:</p>
<ul>
<li>
<p><code id="convert">Markdown.convert(source)</code></p>
<p>The <code>source</code> text must meet the same requirements as the <a href="#text"><code>text</code></a> 
argument of the <a href="#markdown"><code>markdown.markdown</code></a> function.</p>
<p>You should also use this method if you want to process multiple strings
without creating a new instance of the class for each string.</p>
<pre><code>md = markdown.Markdown()
html1 = md.convert(text1)
html2 = md.convert(text2)
</code></pre>
<p>Note that depending on which options and/or extensions are being used,
the parser may need its state reset between each call to <code>convert</code>.</p>
<pre><code>html1 = md.convert(text1)
md.reset()
html2 = md.convert(text2)
</code></pre>
<p>You can also chain calls to <code>reset</code> together:</p>
<pre><code>html3 = md.reset().convert(text3)
</code></pre>
</li>
<li>
<p><code id="convertFile">Markdown.convertFile(**kwargs)</code></p>
<p>The arguments of this method are identical to the arguments of the same
name on the <code>markdown.markdownFromFile</code> function (<a href="#input"><code>input</code></a>, 
<a href="#output"><code>output</code></a>, and <a href="#encoding"><code>encoding</code></a>). As with the 
<a href="#convert"><code>convert</code></a> method, this method should be used to 
process multiple files without creating a new instance of the class for 
each document. State may need to be <code>reset</code> between each call to 
<code>convertFile</code> as is the case with <code>convert</code>.</p>
</li>
</ul>
      </div> <!-- .body -->
    </div> <!-- .bodywrapper -->
  </div> <!-- .documentwrapper -->

  <div class="sphinxsidebar">
    <div class="sphinxsidebarwrapper">
    <h3>Table Of Contents</h3>
    <div class="toc">
<ul>
<li><a href="#using-markdown-as-a-python-library">Using Markdown as a Python Library</a><ul>
<li><a href="#the-basics">The Basics</a></li>
<li><a href="#the-details">The Details</a><ul>
<li><a href="#markdown">markdown.markdown (text [, **kwargs])</a></li>
<li><a href="#markdownFromFile">markdown.markdownFromFile (**kwargs)</a></li>
<li><a href="#Markdown">markdown.Markdown ([**kwargs])</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>


    <h4>Previous topic</h4>
      <p class="topless"><a href="install.html"
         title="previous chapter">Installation</a></p>
    <h4>Next topic</h4>
      <p class="topless"><a href="cli.html"
         title="next chapter">Command Line</a></p>
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="https://github.com/waylan/Python-Markdown/issues"
             >Report a Bug</a></li>
      <li><a href="reference.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="cli.html" title="Command Line"
         accesskey="N">next</a> |</li>
    <li class="right">
      <a href="install.html" title="Installation"
         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.4 documentation</a> &raquo;</li>
    <li><a href="reference.html">Library Reference</a> &raquo;</li>
  </ul>
</div> <!-- .related -->

<div class="footer">&copy; 2010-2012 Python Markdown Project</div>
</body>
</html>