Merge branch 'master' of git://gitorious.org/python-markdown/mainline

6 files changed, 290 insertions, 238 deletions

diff --git a/docs/INSTALL b/docs/INSTALL
index 56d6c78..cdc7dd4 100644
--- a/docs/INSTALL
+++ b/docs/INSTALL
@@ -13,8 +13,11 @@ of Python, open a Python shell and type the following:
 
 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.
+may want to install that if you don't already have it and it's available for 
+your system.
+
+See <http://effbot.org/zone/element-index.htm> for more information or to 
+download the latest version of ElementTree.
 
 The East Way
 ------------
@@ -30,26 +33,23 @@ That's it, your done.
 Installing on Windows
 ---------------------
 
-
-
-Download the Windows installer (.exe) from PyPI:
-
+Download the Windows installer (.exe) from PyPI: 
 <http://pypi.python.org/pypi/Markdown>
 
-Doubleclick the file and follow the instructions.
+Double-click the file and follow the instructions.
 
-If you preffer to manually install Python-Markdown in Windows, download the
+If you prefer 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
+If you plan to use the provided command line script, you need to make sure your
+script directory is on your system path. On a typical Python install of Windows
 the Scripts directory is `C:\Python25\Scripts\`. Adjust according to your 
 system and add that to your system path.
 
-Installing on *nix Sytems
--------------------------
+Installing on *nix Systems
+--------------------------
 
 From the command line do the following:
 
@@ -57,3 +57,17 @@ From the command line do the following:
     tar xvzf markdown-2.0.tar.gz
     cd markdown-2.0/
     sudo python setup.py install
+
+Using the Git Repository
+------------------------
+
+If your the type that like to live on the edge, you may want to keep up with 
+the latest additions and bug fixes in the repository between releases.
+Python-Markdown is maintained in a Git repository on Gitorious.org. To
+get a copy of Python-Markdown from the repository do the following from the
+command line:
+
+    git clone git://gitorious.org/python-markdown/mainline.git python-markdown
+    cd python-markdown
+    python setup.py install
+
diff --git a/docs/README b/docs/README
index b859924..d19a1ea 100644
--- a/docs/README
+++ b/docs/README
@@ -13,46 +13,12 @@ supported by the [Available Extensions][].
 [Available Extensions]: http://www.freewisdom.org/projects/python-markdown/Available_Extensions
 
 
-Installation
-------------
+Documentation
+-------------
 
-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
+Installation and usage documentation is available in the `docs/` directory
+of the distribution and on the project website at 
+<http://freewisdom.org/projects/python-markdown>.
 
 Support
 -------
@@ -60,39 +26,5 @@ 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.
+[bug tracker]: http://www.freewisdom.org/projects/python-markdown/Tickets 
 
-[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
index 6d94e8e..49e3b07 100644
--- a/docs/README.html
+++ b/docs/README.html
@@ -1,91 +1,12 @@
 <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>
-
+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>Documentation</h2>
+<p>Installation and usage documentation is available in the <code>docs/</code> directory
+of the distribution and on the project website at 
+<a href="http://freewisdom.org/projects/python-markdown">http://freewisdom.org/projects/python-markdown</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
+<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://www.freewisdom.org/projects/python-markdown/Tickets">bug tracker</a>.</p>
\ No newline at end of file
diff --git a/docs/command_line.txt b/docs/command_line.txt
new file mode 100644
index 0000000..8ec2522
--- /dev/null
+++ b/docs/command_line.txt
@@ -0,0 +1,57 @@
+Using Python-Markdown on the Command Line
+=========================================
+
+While Python-Markdown is primarily a python library, it also serves as a 
+command line program. While there are many other command line implementations 
+of Markdown, you may not have them installed, or you may prefer to use 
+Python-Markdown's various extensions.
+
+The Basics
+----------
+
+To use ``markdown.py`` from the command line, run it as 
+
+    python markdown.py input_file.txt
+
+or 
+
+    python markdown.py input_file.txt > output_file.html
+
+More Options
+
+If you are using Python 2.3 or higher, you can also use advanced
+command line options to specify encoding or to run extensions.
+
+    $ python markdown.py
+    Usage: markdown.py INPUTFILE [options]
+
+    Options:
+      -h, --help            show this help message and exit
+      -f OUTPUT_FILE, --file=OUTPUT_FILE
+                            write output to OUTPUT_FILE
+      -e ENCODING, --encoding=ENCODING
+                            encoding for input and output files
+      -q, --quiet           suppress all messages
+      -v, --verbose         print info messages
+      -s SAFE_MODE, --safe=SAFE_MODE
+                            safe mode ('replace', 'remove' or 'escape'  user's
+                            HTML tag)
+      --noisy               print debug messages
+      -x EXTENSION, --extension=EXTENSION
+                            load extension EXTENSION
+
+Using Extensions
+----------------
+
+For an extension to be ran this way it must be provided in a module
+named ``mdx_{extensionname}.py`` which should be in your python path,
+e.g. ``mdx_footnotes.py``.  It can then be invoked as by name (the
+part after "mdx_"):
+
+    python markdown.py -x footnotes text_with_footnotes.txt > output.html
+
+If the extension supports config options (see below), you can also
+pass them in as well:
+
+    python markdown.py -x "footnotes(PLACE_MARKER=~~~~~~~~)" input.txt
+
diff --git a/docs/using_as_module.txt b/docs/using_as_module.txt
new file mode 100644
index 0000000..10c276c
--- /dev/null
+++ b/docs/using_as_module.txt
@@ -0,0 +1,123 @@
+Using Markdown as Python Library
+================================
+
+First and foremost, Python-Markdown is intended to be a python library module
+used by various projects to convert Markdown syntax into HTML.
+
+The Basics
+----------
+
+To use markdown as a module:
+
+    import markdown
+    html = markdown.markdown(your_text_string)
+
+Encoded Text
+------------
+
+Note that ``markdown()`` expects either a simple ASCII string or **Unicode** 
+as input 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.  E.g.:
+
+    input_file = codecs.open("some_file.txt", mode="r", encoding="utf8")
+    text = input_file.read()
+    html = markdown.markdown(text, extensions)
+
+If you later want to write it to disk, you should encode it:
+
+    output_file = codecs.open("some_file.html", "w", encoding="utf8")
+    output_file.write(html)
+
+More Options
+------------
+
+If you want to pass more options, you can create an instance of the ``Markdown``
+class yourself and then use ``convert()`` to generate HTML:
+
+    import markdown
+    md = markdown.Markdown(extensions=['footnotes'], 
+                  extension_configs= {'footnotes' : 
+                                     ('PLACE_MARKER','~~~~~~~~')}
+                  encoding='utf8',
+                  safe_mode = True)
+    return md.convert(some_text)
+
+You should also use this method if you want to process multiple strings:
+
+    md = markdown.Markdown()
+    html1 = md.convert(text1)
+    html2 = md.convert(text2)
+
+Working with Files
+------------------
+
+While the Markdown class is only intended to work with Unicode text, some
+encoding/decoding is required for the command line features. These functions 
+and methods are only intended to fit the common use case.
+
+The ``Markdown`` class has the method ``convertFile`` which reads in a file and
+writes out to file-like-object:
+
+    md = markdown.Markdown()
+    md.convertFile(input="in.txt", output="out.html", encoding="uft8")
+
+The markdown module also includes a shortcut function ``markdownFromFile`` that
+wraps the above method.
+
+    markdown.markdownFromFile(input="in.txt", 
+                              output="out.html", 
+                              extensions=[],
+                              encoding="utf8",
+                              safe=False)
+
+In either case, if the ``output`` keyword is passed a file name (i.e.: 
+``output="out.html"``), it will try to write to a file by that name. If
+``output`` is passed a file-like-object (i.e. ``output=StringIO.StringIO()``),
+it will attempt to write out to that object. Finally, is ``output`` is 
+set to ``None``, is will write to ``stdout``.
+
+Using Extensions
+----------------
+
+One of the parameters that you can pass is a list of Extensions. Extensions 
+must be available as python modules either within the ``markdown_extensions``
+package or on your PYTHONPATH with names starting with `mdx_`, followed by the 
+name of the extension.  Thus, ``extensions=['footnotes']`` will first look for 
+the module ``markdown_extensions.footnotes``, then a module named 
+``mdx_footnotes``.   See the documentation specific to the extension you are 
+using for help in specifying configuration settings for that extension.
+
+Note that some extensions may need their state reset between each call to 
+``convert``:
+
+    html1 = md.convert(text1)
+    md.reset()
+    html2 = md.convert(text2)
+
+Safe Mode
+---------
+
+If you are using Markdown on a web system which will transform text provided 
+by untrusted users, you may want to use the "safe_mode" option which ensures 
+that the user's HTML tags are either replaced, removed or escaped. (They can 
+still create links using Markdown syntax.)
+
+* To replace HTML, set ``safe_mode="replace"`` (``safe_mode=True`` still works 
+    for backward compatibility with older versions). The HTML will be replaced 
+    with the text defined in ``markdown.HTML_REMOVED_TEXT`` which defaults to 
+    ``[HTML_REMOVED]``. To replace the HTML with something else:
+
+        markdown.HTML_REMOVED_TEXT = "--RAW HTML IS NOT ALLOWED--"
+        md = markdown.Markdown(safe_mode="replace")
+
+    **Note**: You may edit the value of ``HTML_REMOVED_TEXT`` directly in 
+    markdown.py but you will need to remember to do so every time you upgrade 
+    to a newer version of Markdown.
+
+* To remove HTML, set ``safe_mode="remove"``. Any raw HTML will be completely 
+    stripped from the text with no warning to the author.
+
+* To escape HTML, set ``safe_mode="escape"``. The HTML will be escaped and 
+    included in the document.
+
diff --git a/docs/writing_extensions.txt b/docs/writing_extensions.txt
index df17698..ed4427a 100755
--- a/docs/writing_extensions.txt
+++ b/docs/writing_extensions.txt
@@ -1,4 +1,8 @@
-### Overview
+Writing Extensions for Python-Markdown
+======================================
+
+Overview
+--------
 
 Python-Markdown includes an API for extension writers to plug their own 
 custom functionality and/or syntax into the parser. There are preprocessors
@@ -39,9 +43,9 @@ There are two types of preprocessors: [TextPreprocessors][] and
 
 <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
+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.
 
@@ -57,10 +61,10 @@ 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
+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
+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:
@@ -79,22 +83,22 @@ A pseudo example:
 <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 
+``*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.
+* ``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.
+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:
 
@@ -119,21 +123,21 @@ 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. 
+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)`:
+* ``SimpleTextPattern(pattern)``:
 
-    Returns simple text of `group(2)` of a `pattern`.
+    Returns simple text of ``group(2)`` of a `pattern`.
 
-* `SimpleTagPattern(pattern, tag)`:
+* ``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').
+    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)`:
+* ``SubstituteTagPattern(pattern, tag)``:
 
     Returns an element of type "`tag`" with no children or text (i.e.: 'br').
 
@@ -145,17 +149,17 @@ 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.
+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.
+An ElementTree Postprocessor should inherit from ``markdown.Postprocessor``,
+over-ride the ``run`` method which takes one argument ``root`` and returns 
+either that root element or a modified root element.
 
 A pseudo example:
 
@@ -169,8 +173,8 @@ For specifics on manipulating the ElementTree, see
 
 <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
+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 
@@ -202,8 +206,10 @@ 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.
+[InlinePatterns][]. In such a situation, simply insert the text as you normally
+would and the text will be automatically run through the InlinePatterns. 
+However, if you do *not* want some text to be parsers by InlinePatterns,
+then insert the text as an AtomicString.
 
 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):
@@ -212,10 +218,9 @@ the second cell (``td2``) will be run through InlinePatterns latter):
     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
+    td1.text = markdown.AtomicString("Cell content") # Add plain text content
     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
+    td2.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 
@@ -235,55 +240,55 @@ For more information about working with ElementTree see the ElementTree
 
 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 
+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 
+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.
+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 
+The ``extendMarkdown`` method of a ``markdown.Extension`` class accepts two 
 arguments:
 
-* `md`:
+* ``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`
+    * ``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.inlineStash``
+    * ``md.htmlStash``
+    * ``md.registerExtension()``
 
-* `md_globals`
+* ``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.
+is how the [[HeaderId]] extension works. 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
 
@@ -322,8 +327,8 @@ initialized the first time. Keep that in mind when over-riding the extension's
 <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:
+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] }