aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/AUTHORS36
-rw-r--r--docs/CHANGE_LOG152
-rw-r--r--docs/INSTALL59
-rw-r--r--docs/README98
-rw-r--r--docs/README.html91
-rwxr-xr-xdocs/writing_extensions.txt388
6 files changed, 824 insertions, 0 deletions
diff --git a/docs/AUTHORS b/docs/AUTHORS
new file mode 100644
index 0000000..b4cd939
--- /dev/null
+++ b/docs/AUTHORS
@@ -0,0 +1,36 @@
+Primary Authors
+===============
+
+Yuri Takteyev <http://freewisdom.org/>, who has written much of the current code
+while procrastingating his Ph.D.
+
+Waylan Limberg <http://achinghead.com/>, who has written most of the available
+extensions and later was asked to join Yuri, fixing nummrious bugs, adding
+documentation and making general improvements to the existing codebase.
+
+Artem Yunusov, who as part of a 2008 GSoC project, has refactored inline
+patterns, replaced the NanoDOM with ElementTree support and made various other
+improvements.
+
+Manfed Stienstra <http://www.dwerg.net/>, who wrote the original version of
+the script and is responsible for various parts of the existing codebase.
+
+David Wolever, who refactored the extension API and made other improvements
+as he helped to integrate Markdown into Dr.Project.
+
+Other Contributors
+==================
+
+The incomplete list of individuals below have provided patches
+or otherwise contributed to the project in various ways. We would like to thank
+everyone who has contributed to the progect in any way.
+
+Jeff Balogh
+Sergej Chodarev
+Chris Clark
+Tiago Cogumbreiro
+G. Clark Haynes
+Daniel Krech
+Steward Midwinter
+Malcolm Tredinnick
+and many others to helped by reporting bugs
diff --git a/docs/CHANGE_LOG b/docs/CHANGE_LOG
new file mode 100644
index 0000000..200d5b7
--- /dev/null
+++ b/docs/CHANGE_LOG
@@ -0,0 +1,152 @@
+PYTHON MARKDOWN CHANGELOG
+=========================
+
+August 2008: Updated included extensions to ElementTree. Added a
+seperate commanline script. (v2.0-alpha)
+
+July 2008: Switched from home-grown NanoDOM to ElementTree and
+various related bugs (thanks Artem Yunusov).
+
+June 2008: Fixed issues with nested inline patterns and cleaned
+up testing framework (thanks Artem Yunusov).
+
+May 2008: Added a number of additional extensions to the
+distribution and other minor changes. Moved repo to git from svn.
+
+Mar 2008: Refactored extension api to accept either an
+extension name (as a string) or an instance of an extension
+(Thanks David Wolever). Fixed various bugs and added doc strings.
+
+Feb 2008: Various bugfixes mostly regarding extensions.
+
+Feb 18, 2008: Version 1.7.
+
+Feb 13, 2008: A little code cleanup and better documentation
+and inheritance for pre/post proccessors.
+
+Feb 9, 2008: Doublequotes no longer html escaped and rawhtml
+honors <?foo>, <@foo>, and <%foo> for those who run markdown on
+template syntax.
+
+Dec 12, 2007: Updated docs. Removed encoding arg from Markdown
+and markdown as per list discussion. Clean up in prep for 1.7.
+
+Nov 29, 2007: Added support for images inside links. Also fixed
+a few bugs in the footnote extension.
+
+Nov 19, 2007: `message` now uses python's logging module. Also removed
+limit imposed by recursion in _process_section(). You can now parse as
+long of a document as your memory can handle.
+
+Nov 5, 2007: Moved safe_mode code to a textPostprocessor and added
+escaping option.
+
+Nov 3, 2007: Fixed convert method to accept empty strings.
+
+Oct 30, 2007: Fixed BOM removal (thanks Malcolm Tredinnick). Fixed
+infinite loop in bracket regex for inline links.
+
+Oct 11, 2007: LineBreaks is now an inlinePattern. Fixed HR in
+blockquotes. Refactored _processSection method (see tracker #1793419).
+
+Oct 9, 2007: Added textPreprocessor (from 1.6b).
+
+Oct 8, 2008: Fixed Lazy Blockquote. Fixed code block on first line.
+Fixed empty inline image link.
+
+Oct 7, 2007: Limit recursion on inlinePatterns. Added a 'safe' tag
+to htmlStash.
+
+March 18, 2007: Fixed or merged a bunch of minor bugs, including
+multi-line comments and markup inside links. (Tracker #s: 1683066,
+1671153, 1661751, 1627935, 1544371, 1458139.) -> v. 1.6b
+
+Oct 10, 2006: Fixed a bug that caused some text to be lost after
+comments. Added "safe mode" (user's html tags are removed).
+
+Sept 6, 2006: Added exception for PHP tags when handling html blocks.
+
+August 7, 2006: Incorporated Sergej Chodarev's patch to fix a problem
+with ampersand normalization and html blocks.
+
+July 10, 2006: Switched to using optparse. Added proper support for
+unicode.
+
+July 9, 2006: Fixed the <!--@address.com> problem (Tracker #1501354).
+
+May 18, 2006: Stopped catching unquoted titles in reference links.
+Stopped creating blank headers.
+
+May 15, 2006: A bug with lists, recursion on block-level elements,
+run-in headers, spaces before headers, unicode input (thanks to Aaron
+Swartz). Sourceforge tracker #s: 1489313, 1489312, 1489311, 1488370,
+1485178, 1485176. (v. 1.5)
+
+Mar. 24, 2006: Switched to a not-so-recursive algorithm with
+_handleInline. (Version 1.4)
+
+Mar. 15, 2006: Replaced some instance variables with class variables
+(a patch from Stelios Xanthakis). Chris Clark's new regexps that do
+not trigger midword underlining.
+
+Feb. 28, 2006: Clean-up and command-line handling by Stewart
+Midwinter. (Version 1.3)
+
+Feb. 24, 2006: Fixed a bug with the last line of the list appearing
+again as a separate paragraph. Incorporated Chris Clark's "mailto"
+patch. Added support for <br /> at the end of lines ending in two or
+more spaces. Fixed a crashing bug when using ImageReferencePattern.
+Added several utility methods to Nanodom. (Version 1.2)
+
+Jan. 31, 2006: Added "hr" and "hr/" to BLOCK_LEVEL_ELEMENTS and
+changed <hr/> to <hr />. (Thanks to Sergej Chodarev.)
+
+Nov. 26, 2005: Fixed a bug with certain tabbed lines inside lists
+getting wrapped in <pre><code>. (v. 1.1)
+
+Nov. 19, 2005: Made "<!...", "<?...", etc. behave like block-level
+HTML tags.
+
+Nov. 14, 2005: Added entity code and email autolink fix by Tiago
+Cogumbreiro. Fixed some small issues with backticks to get 100%
+compliance with John's test suite. (v. 1.0)
+
+Nov. 7, 2005: Added an unlink method for documents to aid with memory
+collection (per Doug Sauder's suggestion).
+
+Oct. 29, 2005: Restricted a set of html tags that get treated as
+block-level elements.
+
+Sept. 18, 2005: Refactored the whole script to make it easier to
+customize it and made footnote functionality into an extension.
+(v. 0.9)
+
+Sept. 5, 2005: Fixed a bug with multi-paragraph footnotes. Added
+attribute support.
+
+Sept. 1, 2005: Changed the way headers are handled to allow inline
+syntax in headers (e.g. links) and got the lists to use p-tags
+correctly (v. 0.8)
+
+Aug. 29, 2005: Added flexible tabs, fixed a few small issues, added
+basic support for footnotes. Got rid of xml.dom.minidom and added
+pretty-printing. (v. 0.7)
+
+Aug. 13, 2005: Fixed a number of small bugs in order to conform to the
+test suite. (v. 0.6)
+
+Aug. 11, 2005: Added support for inline html and entities, inline
+images, autolinks, underscore emphasis. Cleaned up and refactored the
+code, added some more comments.
+
+Feb. 19, 2005: Rewrote the handling of high-level elements to allow
+multi-line list items and all sorts of nesting.
+
+Feb. 3, 2005: Reference-style links, single-line lists, backticks,
+escape, emphasis in the beginning of the paragraph.
+
+Nov. 2004: Added links, blockquotes, html blocks to Manfred
+Stienstra's code
+
+Apr. 2004: Manfred's version at http://www.dwerg.net/projects/markdown/
+
diff --git a/docs/INSTALL b/docs/INSTALL
new file mode 100644
index 0000000..56d6c78
--- /dev/null
+++ b/docs/INSTALL
@@ -0,0 +1,59 @@
+Installing Python-Markdown
+==========================
+
+Checking Dependencies
+---------------------
+
+Python-Markdown requires the ElementTree module to be installed. In Python2.5+
+ElementTree is included as part of the standard library. For earlier versions
+of Python, open a Python shell and type the following:
+
+ >>> import cElementTree
+ >>> import ElementTree
+
+If at least one of those does not generate any errors, then you have a working
+copy of ElementTree installed on your system. As cElementTree is faster, you
+may want install that if you don't already have it and it's available for your
+system.
+
+The East Way
+------------
+
+The simplest way to install Python-Markdown is by using SetupTools. As and
+Admin/Root user on your system do:
+
+ easy_install ElementTree
+ easy_install Markdown
+
+That's it, your done.
+
+Installing on Windows
+---------------------
+
+
+
+Download the Windows installer (.exe) from PyPI:
+
+<http://pypi.python.org/pypi/Markdown>
+
+Doubleclick the file and follow the instructions.
+
+If you preffer to manually install Python-Markdown in Windows, download the
+Zip file, unzip it, and on the command line in the directory you unzipped to:
+
+ python setup.py install
+
+If you plan to use the provided commandline script, you need to make sure your
+script directory is on your system path. On a typical Python install on Windows
+the Scripts directory is `C:\Python25\Scripts\`. Adjust according to your
+system and add that to your system path.
+
+Installing on *nix Sytems
+-------------------------
+
+From the command line do the following:
+
+ wget http://pypi.python.org/packages/source/M/Markdown/markdown-2.0.tar.gz
+ tar xvzf markdown-2.0.tar.gz
+ cd markdown-2.0/
+ sudo python setup.py install
diff --git a/docs/README b/docs/README
new file mode 100644
index 0000000..b859924
--- /dev/null
+++ b/docs/README
@@ -0,0 +1,98 @@
+[Python-Markdown][]
+===================
+
+This is a Python implementation of John Gruber's [Markdown][].
+It is almost completely compliant with the reference implementation,
+though there are a few known issues. See [Features][] for information
+on what exactly is supported and what is not. Additional features are
+supported by the [Available Extensions][].
+
+[Python-Markdown]: http://freewisdom.org/projects/python-markdown
+[Markdown]: http://daringfireball.net/projects/markdown/
+[Features]: http://www.freewisdom.org/projects/python-markdown/Features
+[Available Extensions]: http://www.freewisdom.org/projects/python-markdown/Available_Extensions
+
+
+Installation
+------------
+
+To install Python Markdown [download][] the zip file and extract the
+files. If you want to install markdown as a module into your python
+tree, run `sudo python setup.py install` from a directory where you
+unzip the files.
+
+[download]: http://sourceforge.net/project/showfiles.php?group_id=153041
+
+
+Command Line Usage
+------------------
+
+To use markdown.py from the command line, run it as
+
+ python markdown.py <input_file>
+
+or
+
+ python markdown.py <input_file> > <output_file>
+
+For more details, use the `-h` or `--help` options from the command line
+or read the [Command Line Docs][] available online.
+
+[Command Line Docs]: http://www.freewisdom.org/projects/python-markdown/Command_Line
+
+
+
+Using as a Python Module
+------------------------
+
+To use markdown as a module:
+
+ import markdown
+ html = markdown.markdown(your_text_string)
+
+For more details see the [Module Docs][].
+
+[Module Docs]: http://www.freewisdom.org/projects/python-markdown/Using_as_a_Module
+
+Support
+-------
+
+You may ask for help and discuss various other issues on the [mailing list][] and report bugs on the [bug tracker][].
+
+[mailing list]: http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss
+[bug tracker]: http://sourceforge.net/tracker/?func=add&group_id=153041&atid=790198
+
+
+Credits
+-------
+
+* Most of the code currently in the module was written by [Yuri Takhteyev][]
+ while procrastinating from his Ph.D.
+* The original version of this script was written by [Manfred Stienstra][],
+ who is responsible for about a quarter of the code.
+* Many recent bugs are being fixed by [Waylan Limberg][].
+
+Other contributions:
+
+* Daniel Krech provided the setup.py script.
+* G. Clark Haynes submitted a patch for indented lists.
+* Tiago Cogumbreiro submitted an email autolink fix.
+* Sergej Chodarev submitted a patch for treatment of `<hr/>` tags.
+* Chris Clark submitted a patch to handle `<mailto:...>` syntax and a reg ex
+ for "smart" emphasis (ignoring underscores within a word).
+* Steward Midwinter wrote command-line parser and cleaned up comments.
+* Many other people helped by reporting bugs.
+
+[Yuri Takhteyev]: http://www.freewisdom.org
+[Manfred Stienstra]: http://www.dwerg.net/
+[Waylan Limberg]: http://achinghead.com/
+
+
+License
+-------
+
+The code is dual-licensed under [GPL][] and [BSD License][]. Other
+licensing arrangements can be discussed.
+
+[GPL]: http://www.gnu.org/copyleft/gpl.html)
+[BSD License]: http://www.opensource.org/licenses/bsd-license.php
diff --git a/docs/README.html b/docs/README.html
new file mode 100644
index 0000000..6d94e8e
--- /dev/null
+++ b/docs/README.html
@@ -0,0 +1,91 @@
+<h1><a href="http://freewisdom.org/projects/python-markdown">Python-Markdown</a></h1>
+<p>This is a Python implementation of John Gruber's <a href="http://daringfireball.net/projects/markdown/">Markdown</a>.
+ It is almost completely compliant with the reference implementation,
+ though there are a few known issues. See <a href="http://www.freewisdom.org/projects/python-markdown/Features">Features</a> for information
+ on what exactly is supported and what is not. Additional features are
+ supported by the <a href="http://www.freewisdom.org/projects/python-markdown/Available_Extensions">Available Extensions</a>.
+</p>
+
+<h2>Installation</h2>
+<p>To install Python Markdown <a href="http://sourceforge.net/project/showfiles.php?group_id=153041">download</a> the zip file and extract the
+ files. If you want to install markdown as a module into your python
+ tree, run <code>sudo python setup.py install</code> from a directory where you
+ unzip the files.
+</p>
+
+<h2>Command Line Usage</h2>
+<p>To use markdown.py from the command line, run it as
+</p>
+<pre><code>python markdown.py &lt;input_file&gt;
+</code></pre><p>or
+</p>
+<pre><code>python markdown.py &lt;input_file&gt; &gt; &lt;output_file&gt;
+</code></pre><p>For more details, use the <code>-h</code> or <code>--help</code> options from the command line
+ or read the <a href="http://www.freewisdom.org/projects/python-markdown/Command_Line">Command Line Docs</a> available online.
+</p>
+
+<h2>Using as a Python Module</h2>
+<p>To use markdown as a module:
+</p>
+<pre><code>import markdown
+html = markdown.markdown(your_text_string)
+</code></pre><p>For more details see the <a href="http://www.freewisdom.org/projects/python-markdown/Using_as_a_Module">Module Docs</a>.
+</p>
+
+<h2>Support</h2>
+<p>You may ask for help and discuss various other issues on the <a href="http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss">mailing list</a> and report bugs on the <a href="http://sourceforge.net/tracker/?func=add&amp;group_id=153041&amp;atid=790198">bug tracker</a>.
+</p>
+
+<h2>Credits</h2>
+<ul>
+ <li>
+ Most of the code currently in the module was written by <a href="http://www.freewisdom.org">Yuri Takhteyev</a>
+ while procrastinating from his Ph.D.
+ </li>
+
+ <li>
+ The original version of this script was written by <a href="http://www.dwerg.net/">Manfred Stienstra</a>,
+ who is responsible for about a quarter of the code.
+ </li>
+
+ <li>
+ Many recent bugs are being fixed by <a href="http://achinghead.com/">Waylan Limberg</a>.
+ </li>
+</ul>
+<p>Other contributions:
+</p>
+<ul>
+ <li>
+ Daniel Krech provided the setup.py script.
+ </li>
+
+ <li>
+ G. Clark Haynes submitted a patch for indented lists.
+ </li>
+
+ <li>
+ Tiago Cogumbreiro submitted an email autolink fix.
+ </li>
+
+ <li>
+ Sergej Chodarev submitted a patch for treatment of <code>&lt;hr/&gt;</code> tags.
+ </li>
+
+ <li>
+ Chris Clark submitted a patch to handle <code>&lt;mailto:...&gt;</code> syntax and a reg ex
+ for &quot;smart&quot; emphasis (ignoring underscores within a word).
+ </li>
+
+ <li>
+ Steward Midwinter wrote command-line parser and cleaned up comments.
+ </li>
+
+ <li>
+ Many other people helped by reporting bugs.
+ </li>
+</ul>
+
+<h2>License</h2>
+<p>The code is dual-licensed under <a href="http://www.gnu.org/copyleft/gpl.html)">GPL</a> and <a href="http://www.opensource.org/licenses/bsd-license.php">BSD License</a>. Other
+ licensing arrangements can be discussed.
+</p> \ No newline at end of file
diff --git a/docs/writing_extensions.txt b/docs/writing_extensions.txt
new file mode 100755
index 0000000..df17698
--- /dev/null
+++ b/docs/writing_extensions.txt
@@ -0,0 +1,388 @@
+### Overview
+
+Python-Markdown includes an API for extension writers to plug their own
+custom functionality and/or syntax into the parser. There are preprocessors
+which allow you to alter the source before it is passed to the parser,
+inline patterns which allow you to add, remove or override the syntax of
+any inline elements, and postprocessors which allow munging of the
+output of the parser before it is returned.
+
+As the parser builds an [ElementTree][] object which is later rendered
+as Unicode text, there are also some helpers provided to make manipulation of
+the tree easier. Each part of the API is discussed in its respective
+section below. You may find reading the source of some [[Available Extensions]]
+helpful as well. For example, the [[Footnotes]] extension uses most of the
+features documented here.
+
+* [Preprocessors][]
+ * [TextPreprocessors][]
+ * [Line Preprocessors][]
+* [InlinePatterns][]
+* [Postprocessors][]
+ * [ElementTree Postprocessors][]
+ * [TextProstprocessors][]
+* [Working with the ElementTree][]
+* [Integrating your code into Markdown][]
+ * [extendMarkdown][]
+ * [registerExtension][]
+ * [Config Settings][]
+ * [makeExtension][]
+
+<h3 id="preprocessors">Preprocessors</h3>
+
+Preprocessors munge the source text before it is passed into the Markdown
+core. This is an excellent place to clean up bad syntax, extract things the
+parser may otherwise choke on and perhaps even store it for later retrieval.
+
+There are two types of preprocessors: [TextPreprocessors][] and
+[Line Preprocessors][].
+
+<h4 id="textpreprocessors">TextPreprocessors</h4>
+
+TextPreprocessors should inherit from `markdown.TextPreprocessor` and implement
+a `run` method with one argument `text`. The `run` method of each
+TextPreprocessor will be passed the entire source text as a single Unicode
+string and should either return that single Unicode string, or an altered
+version of it.
+
+For example, a simple TextPreprocessor that normalizes newlines [^1] might look
+like this:
+
+ class NormalizePreprocessor(markdown.TextPreprocessor):
+ def run(self, text):
+ return text.replace("\r\n", "\n").replace("\r", "\n")
+
+[^1]: It should be noted that Markdown already normalizes newlines. This
+example is for illustrative purposes only.
+
+<h4 id="linepreprocessors">Line Preprocessors</h4>
+
+Line Preprocessors should inherit from `markdown.Preprocessor` and implement
+a `run` method with one argument `lines`. The `run` method of each Line
+Preprocessor will be passed the entire source text as a list of Unicode strings.
+Each string will contain one line of text. The `run` method should return
+either that list, or an altered list of Unicode strings.
+
+A pseudo example:
+
+ class MyPreprocessor(markdown.Preprocessor):
+ def run(self, lines):
+ new_lines = []
+ for line in lines:
+ m = MYREGEX.match(line)
+ if m:
+ # do stuff
+ else:
+ new_lines.append(line)
+ return new_lines
+
+<h3 id="inlinepatterns">Inline Patterns</h3>
+
+Inline Patterns implement the inline HTML element syntax for Markdown such as
+`*emphasis*` or `[links](http://example.com)`. Pattern objects should be
+instances of classes that inherit from `markdown.Pattern` or one of its
+children. Each pattern object uses a single regular expression and must have
+the following methods:
+
+* `getCompiledRegExp()`: Returns a compiled regular expression.
+* `handleMatch(m)`: Accepts a match object and returns an ElementTree
+element of a plain Unicode string.
+
+Note that any regular expression returned by `getCompiledRegExp` must capture
+the whole block. Therefore, they should all start with `r'^(.*?)'` and end
+with `r'(.*?)!'. When using the default `getCompiledRegExp()` method provided
+in the `Pattern` you can pass in a regular expression without that and
+`getCompiledRegExp` will wrap your expression for you. This means that the first
+group of your match will be `m.group(2)` as `m.group(1)` will match everything
+before the pattern.
+
+For an example, consider this simplified emphasis pattern:
+
+ class EmphasisPattern(markdown.Pattern):
+ def handleMatch(self, m):
+ el = markdown.etree.Element('em')
+ el.text = m.group(3)
+ return el
+
+As discussed in [Integrating Your Code Into Markdown][], an instance of this
+class will need to be provided to Markdown. That instance would be created
+like so:
+
+ # an oversimplified regex
+ MYPATTERN = r'\*([^*]+)\*'
+ # pass in pattern and create instance
+ emphasis = EmphasisPattern(MYPATTERN)
+
+Actually it would not be necessary to create that pattern (and not just because
+a more sophisticated emphasis pattern already exists in Markdown). The fact is,
+that example pattern is not very DRY. A pattern for `**strong**` text would
+be almost identical, with the exception that it would create a 'strong' element.
+Therefore, Markdown provides a number of generic pattern classes that can
+provide some common functionality. For example, both emphasis and strong are
+implemented with separate instances of the `SimpleTagPettern` listed below.
+Feel free to use or extend any of these Pattern classes.
+
+**Generic Pattern Classes**
+
+* `SimpleTextPattern(pattern)`:
+
+ Returns simple text of `group(2)` of a `pattern`.
+
+* `SimpleTagPattern(pattern, tag)`:
+
+ Returns an element of type "`tag`" with a text attribute of `group(3)`
+ of a `pattern`. `tag` should be a string of a HTML element (i.e.: 'em').
+
+* `SubstituteTagPattern(pattern, tag)`:
+
+ Returns an element of type "`tag`" with no children or text (i.e.: 'br').
+
+There may be other Pattern classes in the Markdown source that you could extend
+or use as well. Read through the source and see if there is anything you can
+use. You might even get a few ideas for different approaches to your specific
+situation.
+
+<h3 id="postprocessors">Postprocessors</h3>
+
+Postprocessors manipulate a document after it has passed through the Markdown
+core. This is were stored text gets added back in such as a list of footnotes,
+a table of contents or raw html.
+
+There are two types of postprocessors: [ElementTree Postprocessors][] and
+[TextPostprocessors][].
+
+<h4 id="etpostprocessors">ElementTree Postprocessors</h4>
+
+An ElementTree Postprocessor should inherit from `markdown.Postprocessor`,
+over-ride the `run` method which takes one argument `root` and return either
+that root element or a modified root element.
+
+A pseudo example:
+
+ class MyPostprocessor(markdown.Postprocessor):
+ def run(self, root):
+ #do stufff
+ return my_modified_root
+
+For specifics on manipulating the ElementTree, see
+[Working with the ElementTree][] below.
+
+<h4 id="textpostprocessors">TextPostprocessors</h4>
+
+A TextPostprocessor should inherit from `markdown.TextPostprocessor` and
+over-ride the `run` method which takes one argument `text` and returns a
+Unicode string.
+
+TextPostprocessors are run after the ElementTree has been serialized back into
+Unicode text. For example, this may be an appropriate place to add a table of
+contents to a document:
+
+ class TocTextPostprocessor(markdown.TextPostprocessor):
+ def run(self, text):
+ return MYMARKERRE.sub(MyToc, text)
+
+<h3 id="working_with_et">Working with the ElementTree</h3>
+
+As mentioned, the Markdown parser converts a source document to an
+[ElementTree][] object before serializing that back to Unicode text.
+Markdown has provided some helpers to ease that manipulation within the context
+of the Markdown module.
+
+First, to get access to the ElementTree module import ElementTree from
+``markdown`` rather than importing it directly. This will ensure you are using
+the same version of ElementTree as markdown. The module is named ``etree``
+within Markdown.
+
+ from markdown import etree
+
+``markdown.etree`` tries to import ElementTree from any known location, first
+as a standard library module (from ``xml.etree`` in Python 2.5), then as a third
+party package (``Elementree``). In each instance, ``cElementTree`` is tried
+first, then ``ElementTree`` if the faster C implementation is not available on
+your system.
+
+Sometimes you may want text inserted into an element to be parsed by
+[InlinePatterns][]. In such a situation, simply insert the text into an
+`inline` tag and the text will be automatically run through the InlinePatterns.
+
+Here's a basic example which creates an HTML table (note that the contents of
+the second cell (``td2``) will be run through InlinePatterns latter):
+
+ table = etree.Element("table")
+ table.set("cellpadding", "2") # Set cellpadding to 2
+ tr = etree.SubElement(table, "tr") # Add child tr to table
+ td1 = etree.SubElement(tr, "td") # Add child td1 to tr
+ td1.text = "Cell content" # Add plain text content to td1 element
+ td2 = etree.SubElement(tr, "td") # Add second td to tr
+ inline = etree.SubElement(td2, "inline") # Add an inline element to td2
+ inline.text = "Some *text* with **inline** formatting." # Add markup text
+ table.tail = "Text after table" # Added text after table Element
+
+You can also manipulate an existing tree. Consider the following example which
+adds a ``class`` attribute to all ``a`` elements:
+
+ def set_link_class(self, element):
+ for child in element:
+ if child.tag == "a":
+ child.set("class", "myclass") #set the class attribute
+ set_link_class(child) # run recursively on children
+
+For more information about working with ElementTree see the ElementTree
+[Documentation](http://effbot.org/zone/element-index.htm)
+([Python Docs](http://docs.python.org/lib/module-xml.etree.ElementTree.html)).
+
+<h3 id="integrating_into_markdown">Integrating Your Code Into Markdown
+
+Once you have the various pieces of your extension built, you need to tell
+Markdown about them and ensure that they are run in the proper sequence.
+Markdown accepts a `Extension` instance for each extension. Therefore, you
+will need to define a class that extends `markdown.Extension` and over-rides
+the `extendMarkdown` method. Within this class you will manage configuration
+options for your extension and attach the various processors and patterns to
+the Markdown instance.
+
+It is important to note that the order of the various processors and patterns
+matters. For example, if we replace `http://...` links with <a> elements, and
+*then* try to deal with inline html, we will end up with a mess. Therefore,
+the various types of processors and patterns are stored within an instance of
+the Markdown class within lists. Your `Extension` class will need to manipulate
+those lists appropriately. You may insert instances of your processors and
+patterns into the appropriate location in a list, remove a built-in instances,
+or replace a built-in instance with your own.
+
+<h4 id="extendmarkdown">`extendMarkdown`</h4>
+
+The `extendMarkdown` method of a `markdown.Extension` class accepts two
+arguments:
+
+* `md`:
+
+ A pointer to the instance of the Markdown class. You should use this to
+ access the lists of processors and patterns. They are found under the
+ following attributes:
+
+ * `md.textPreprocessors`
+ * `md.preprocessors`
+ * `md.inlinePatterns`
+ * `md.postpreprocessors`
+ * `md.textPostprocessors`
+
+ Some other things you may want to access in the markdown instance are:
+
+ * `md.inlineStash`
+ * `md.htmlStash`
+ * `md.registerExtension()`
+
+* `md_globals`
+
+ Contains all the various global variables within the markdown module.
+
+Of course, with access to those items, theoretically you have the option to
+changing anything through various [monkey_patching][] techniques. In fact, this
+is how both the [[HeaderId]] and [[CodeHilite]] extensions work. However, you
+should be aware that the various undocumented or private parts of markdown may
+change without notice and your monkey_patches may break with a new release.
+Therefore, what you really should be doing is inserting processors and patterns
+into the markdown pipeline. Consider yourself warned.
+
+[monkey_patching]: http://en.wikipedia.org/wiki/Monkey_patch
+
+<h4 id="registerextension">registerExtension</h4>
+
+Some extensions may need to have their state reset between multiple runs of the
+Markdown class. For example, consider the following use of the [[Footnotes]]
+extension:
+
+ md = markdown.Markdown(extensions=['footnotes'])
+ html1 = md.convert(text_with_footnote)
+ md.reset()
+ html2 = md.convert(text_without_footnote)
+
+Without calling ``reset``, the footnote definitions from the first document will
+be inserted into the second document as they are still stored within the class
+instance. Therefore the ``Extension`` class needs to define a ``reset`` method
+that will reset the state of the extension (i.e.: ``self.footnotes = {}``).
+However, as many extensions do not have a need for ``reset``, ``reset`` is only
+called on extensions that are registered.
+
+To register an extension, call ``md.registerExtension`` from within your
+``extendMarkdown`` method:
+
+
+ def extendMarkdown(self, md, md_globals):
+ md.registerExtension(self)
+ # insert processors and patterns here
+
+Then, each time ``reset`` is called on the Markdown instance, the ``reset``
+method of each registered extension will be called as well. You should also
+note that ``reset`` will be called on each registered extension after it is
+initialized the first time. Keep that in mind when over-riding the extension's
+``reset`` method.
+
+<h4 id="configsettings">Config Settings</h4>
+
+If an extension uses any parameters that the user may want to change,
+those parameters should be stored in `self.config` of your `markdown.Extension`
+class in the following format:
+
+ self.config = {parameter_1_name : [value1, description1],
+ parameter_2_name : [value2, description2] }
+
+When stored this way the config parameters can be over-ridden from the
+command line or at the time Markdown is initiated:
+
+ markdown.py -x myextension(SOME_PARAM=2) inputfile.txt > output.txt
+
+Note that parameters should always be assumed to be set to string
+values, and should be converted at run time. For example:
+
+ i = int(self.getConfig("SOME_PARAM"))
+
+<h4 id="makeextension">`makeExtension`</h4>
+
+Each extension should ideally be placed in its own module starting
+with the ``mdx_`` prefix (e.g. ``mdx_footnotes.py``). The module must
+provide a module-level function called ``makeExtension`` that takes
+an optional parameter consisting of a dictionary of configuration over-rides
+and returns an instance of the extension. An example from the footnote
+extension:
+
+ def makeExtension(configs=None) :
+ return FootnoteExtension(configs=configs)
+
+By following the above example, when Markdown is passed the name of your
+extension as a string (i.e.: ``'footnotes'``), it will automatically import
+the module and call the ``makeExtension`` function initiating your extension.
+
+You may have noted that the extensions packaged with Python-Markdown do not
+use the ``mdx_`` prefix in their module names. This is because they are all
+part of the ``markdown_extensions`` package. Markdown will first try to import
+from ``markdown_extensions.extname`` and upon failure, ``mdx_extname``. If both
+fail, Markdown will continue without the extension.
+
+However, Markdown will also accept an already existing instance of an extension.
+For example:
+
+ import markdown
+ import myextension
+ configs = {...}
+ myext = myextension.MyExtension(configs=configs)
+ md = markdown.Markdown(extensions=[myext])
+
+This is useful if you need to implement a large number of extensions with more
+than one residing in a module.
+
+[Preprocessors]: #preprocessors
+[TextPreprocessors]: #textpreprocessors
+[Line Preprocessors]: #linepreprocessors
+[InlinePatterns]: #inlinepatterns
+[Postprocessors]: #postprocessors
+[ElementTree Postprocessors]: #etpostprocessors
+[TextProstprocessors]: #textpostprocessors
+[Working with the ElementTree]: #working_with_et
+[Integrating your code into Markdown]: #integrating_into_markdown
+[extendMarkdown]: #extendmarkdown
+[registerExtension]: #registerextension
+[Config Settings]: #configsettings
+[makeExtension]: #makeextension
+[ElementTree]: http://effbot.org/zone/element-index.htm