Added documentation for OrderedDict.

1 files changed, 84 insertions, 33 deletions

diff --git a/docs/writing_extensions.txt b/docs/writing_extensions.txt
index 35bc3e2..bbddb1b 100755..100644
--- a/docs/writing_extensions.txt
+++ b/docs/writing_extensions.txt
@@ -26,7 +26,7 @@ features documented here.
 * [Working with the ElementTree][]
 * [Integrating your code into Markdown][]
     * [extendMarkdown][]
-    * [Treaps][]
+    * [OrderedDict][]
     * [registerExtension][]
     * [Config Settings][]
     * [makeExtension][]
@@ -266,10 +266,10 @@ 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 in [Treaps][]. Your ``Extension`` class will need to 
-manipulate those Treaps appropriately. You may insert instances of your 
-processors and patterns into the appropriate location in a Treap, remove a 
-built-in instance, or replace a built-in instance with your own.
+the Markdown class in [OrderedDict][]s. Your ``Extension`` class will need to 
+manipulate those OrderedDicts appropriately. You may insert instances of your 
+processors and patterns into the appropriate location in an OrderedDict, remove
+a built-in instance, or replace a built-in instance with your own.
 
 <h4 id="extendmarkdown">`extendMarkdown`</h4>
 
@@ -279,8 +279,8 @@ arguments:
 * ``md``:
 
     A pointer to the instance of the Markdown class. You should use this to 
-    access the Treaps of processors and patterns. They are found under the 
-    following attributes:
+    access the [OrderedDict][]s of processors and patterns. They are found 
+    under the following attributes:
 
     * ``md.preprocessors``
     * ``md.inlinePatterns``
@@ -307,43 +307,94 @@ Consider yourself warned.
 
 [monkey_patching]: http://en.wikipedia.org/wiki/Monkey_patch
 
-<h4 id="treaps">Treaps</h4>
+A simple example:
 
-A treap is a binary search tree that orders nodes by accepting a priority
-attribute with a node, a well as a key to store the node. The priority 
-determines the node's location in the heap. Each new node entry causes the 
-heap to re-balance. The name "treap" is a composition of "tree" and "heap".
+    class MyExtension(makrdown.Extension):
+        def extendMarkdown(self, md, md_globals):
+            # Insert instance of 'mypattern' before 'references' pattern
+            md.inlinePatterns.add('mypattern', MyPattern(md), '<references')
 
-An example:
+<h4 id="ordereddict">OrderedDict</h4>
 
-    tr = markdown.Treap()
-    tr.add("key1", Object1, "_begin")
-    tr.add("key2", Object2, ">key1")
-    tr.add("key3", Object3, "<key2")
-    tr.add("key4", Object4, "_end")
+An OrderedDict is a dictionary like object that retains the order of it's
+items. The items are ordered in the order in which they were appended to
+the OrderedDict. However, an item can also be inserted into the OrderedDict
+in a specific location in relation to the existing items.
 
-Note that the priority can consist of a few different values. The special 
-strings ``"_begin"`` and ``"_end"`` insert that node at the beginning or end
-of the sorted heap. A less-than sign (``<``) followed by an existing key (i.e.:
-``"<key2"``) inserts that node before that existing key. A greater-than sign
-(``>``) followed by an existing key (i.e.: ``">key1"``) inserts that node after
-that existing key.
+Think of OrderedDict as a combination of a list and a dictionary as it has 
+methods common to both. For example, you can get and set items using the 
+``od[key] = value`` syntax and the methods ``keys()``, ``values()``, and 
+``items()`` work as expected with the keys, values and items returned in the 
+proper order. At the same time, you can use ``insert()``, ``append()``, and 
+``index()`` as you would with a list.
 
-Once a treap is created, the nodes are available via key:
+Generally speaking, within Markdown extensions you will be using the special 
+helper method ``add()`` to add additional items to an existing OrderedDict. 
 
-    MyNode = tr['somekey']
+The ``add()`` method accepts three arguments:
 
-Therefore, to delete an existing node:
+* **``key``**: A string. The key is used for later reference to the item.
+* **``value``**: The object instance stored in this item.
+* **``location``**: Optional. The items location in relation to other items. 
+  Note that the location can consist of a few different values:
 
-    del tr['somekey']
+    * The special strings ``"_begin"`` and ``"_end"`` insert that item at the 
+      beginning or end of the OrderedDict respectively. 
+    
+    * A less-than sign (``<``) followed by an existing key (i.e.: 
+      ``"<somekey"``) inserts that item before the existing key.
+    
+    * A greater-than sign (``>``) followed by an existing key (i.e.: 
+      ``">somekey"``) inserts that item after the existing key. 
+
+Consider the following example:
+
+    >>> import markdown
+    >>> od = markdown.OrderedDict()
+    >>> od['one'] =  1           # The same as: od.add('one', 1, '_begin')
+    >>> od['three'] = 3          # The same as: od.add('three', 3, '>one')
+    >>> od['four'] = 4           # The same as: od.add('four', 4, '_end')
+    >>> od.items()
+    [("one", 1), ("three", 3), ("four", 4)]
+
+Note that when building an OrderedDict in order, the extra features of the
+``add`` method offer no real value and are not necessary. However, when 
+manipulating an existing OrderedDict, ``add`` can be very helpful. So lets 
+insert another item into the OrderedDict.
+
+    >>> od.add('two', 2, '>one')         # Insert after 'one'
+    >>> od.values()
+    [1, 2, 3, 4]
+
+Now lets insert another item.
+
+    >>> od.add('twohalf', 2.5, '<three') # Insert before 'three'
+    >>> od.keys()
+    ["one", "two", "twohalf", "three", "four"]
+
+Note that we also could have set the location of "twohalf" to be 'after two'
+(i.e.: ``'>two'``). However, it's unlikely that you will have control over the 
+order in which extensions will be loaded, and this could affect the final 
+sorted order of an OrderedDict. For example, suppose a extension adding 
+'twohalf' in the above examples was loaded before a separate  extension which 
+adds 'two'. You may need to take this into consideration when adding your 
+extension components to the various markdown OrderedDicts.
+
+Once an OrderedDict is created, the items are available via key:
+
+    MyNode = od['somekey']
+
+Therefore, to delete an existing item:
+
+    del od['somekey']
 
-To change the value of an existing node (leaving priority the same):
+To change the value of an existing item (leaving location unchanged):
 
-    tr['somekey'] = MyNewObject
+    od['somekey'] = MyNewObject()
 
-To change the priority of an existing object:
+To change the location of an existing item:
 
-    tr.link('somekey', '<otherkey')
+    t.link('somekey', '<otherkey')
 
 <h4 id="registerextension">registerExtension</h4>
 
@@ -438,7 +489,7 @@ than one residing in a module.
 [Working with the ElementTree]: #working_with_et
 [Integrating your code into Markdown]: #integrating_into_markdown
 [extendMarkdown]: #extendmarkdown
-[Treaps]: #treaps
+[OrderedDict]: #ordereddict
 [registerExtension]: #registerextension
 [Config Settings]: #configsettings
 [makeExtension]: #makeextension