aboutsummaryrefslogtreecommitdiffstats
path: root/writing_extensions.txt
diff options
context:
space:
mode:
authorArtem Yunusov <nedrlab@gmail.com>2008-08-12 02:38:36 +0500
committerArtem Yunusov <nedrlab@gmail.com>2008-08-12 02:38:36 +0500
commit2215f99b0c5d82b3d53306f762a6135adeade384 (patch)
treebbcdf771bd571960c1be3eadf4a11c130df08e15 /writing_extensions.txt
parentfe8a2ff307ca2535e841e546cabfa31ce296d4ef (diff)
downloadmarkdown-2215f99b0c5d82b3d53306f762a6135adeade384.tar.gz
markdown-2215f99b0c5d82b3d53306f762a6135adeade384.tar.bz2
markdown-2215f99b0c5d82b3d53306f762a6135adeade384.zip
Writing extensions guide updated.
Diffstat (limited to 'writing_extensions.txt')
-rwxr-xr-x[-rw-r--r--]writing_extensions.txt79
1 files changed, 65 insertions, 14 deletions
diff --git a/writing_extensions.txt b/writing_extensions.txt
index 2ae279c..dbb4dd4 100644..100755
--- a/writing_extensions.txt
+++ b/writing_extensions.txt
@@ -7,9 +7,9 @@ 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][] DOM object which is later rendered
+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 DOM tree easier. Each part of the API is discussed in its respective
+the tree easier. Each part of the API is discussed in its respective
section below. You may find reading the source of some [[existing extensions]]
helpful as well. For example, the [[footnote]] extension uses most of the
features documented here.
@@ -19,9 +19,9 @@ features documented here.
* [Line Preprocessors][]
* [InlinePatterns][]
* [Postprocessors][]
- * [DOM Postprocessors][]
+ * [ElementTree Postprocessors][]
* [TextProstprocessors][]
-* [Working with the DOM][]
+* [Working with the ElementTree][]
* [Integrating your code into Markdown][]
* [extendMarkdown][]
* [Config Settings][]
@@ -147,12 +147,12 @@ 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: [DOM Postprocessors][] and
+There are two types of postprocessors: [ElementTree Postprocessors][] and
[TextPostprocessors][].
-<h4 id="dompostprocessors">DOM Postprocessors</h4>
+<h4 id="etpostprocessors">ElementTree Postprocessors</h4>
-A DOM Postprocessor should inherit from `markdown.Postprocessor` and over-ride
+A ElementTree Postprocessor should inherit from `markdown.Postprocessor` and over-ride
the `run` method which takes one argument `root` and should return either
that root element or a modified root element.
@@ -163,7 +163,7 @@ A pseudo example:
#do stufff
return my_modified_root
-For specifics on manipulating the DOM, see [Working with the DOM][] below.
+For specifics on manipulating the ElementTree, see [Working with the ElementTree][] below.
<h4 id="textpostprocessors">TextPostprocessors</h4>
@@ -171,7 +171,7 @@ 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 DOM has been serialized back into Unicode
+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:
@@ -179,12 +179,63 @@ to a document:
def run(self, text):
return MYMARKERRE.sub(MyToc, text)
-<h3 id="working_with_dom">Working with the DOM</h3>
+<h3 id="working_with_et">Working with the ElementTree</h3>
As mentioned, the Markdown parser converts a source document to an
-[ElementTree][] DOM object before serializing that back to Unicode text.
+[ElementTree][] 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...
+of the Markdown module.
+First of all, to get access to the ElementTree module object you should use:
+
+ import markdown
+ etree = markdown.etree
+
+It's try to import ElementTree from any known places, first as standard Python
+cElementTree/ElementTree module, then as separately installed cElementTree/ElementTree.
+Another thing you need to know is that all text data, included in <inline> tag will be
+processed later with [InlinePatterns][].
+
+Example below show basic ElementTree functionality:
+
+ table = etree.Element("table")
+ table.set("cellpadding", "2") # Set cellpadding to 2
+ tr = etree.SubElement(table, "tr") # Added child tr to table
+ td = etree.SubElement(tr, "td") # Added child td to tr
+ td.text = "Cell content" # Added text content to td element
+ table.tail = "Text after table" # Added text after table Element
+ print etree.tostring(table) # Serialized our table
+
+Now let's write a simple ElementTree Postprocessor, that will add "class" attribute
+to all "a" elements:
+
+ class AttrPostprocessor(markdown.Postprocessor):
+
+ def _findElement(self, element, name):
+ """
+ find elements with @name and return list
+
+ Keyword arguments:
+
+ * element: ElementTree Element
+ * name: tag name to search
+
+ """
+ result = []
+ for child in element:
+ if child.tag == name:
+ result.append(child)
+ result += self._findElement(child, name)
+ return result
+
+ def run(self, root):
+
+ for element in self._findElement(root, "a"):
+ element.set("class", "MyClass") # Set "class" atribute
+
+ retrun root
+
+For more information about working with ElementTree visit
+ElementTree [official site](http://effbot.org/zone/element-index.htm).
<h3 id="integrating_into_markdown">Integrating Your Code Into Markdown
@@ -288,9 +339,9 @@ than one residing in a module.
[Line Preprocessors]: #linepreprocessors
[InlinePatterns]: #inlinepatterns
[Postprocessors]: #postprocessors
-[DOM Postprocessors]: #dompostprocessors
+[ElementTree Postprocessors]: #etpostprocessors
[TextProstprocessors]: #textpostprocessors
-[Working with the DOM]: #working_with_dom
+[Working with the ElementTree]: #working_with_et
[Integrating your code into Markdown]: #integrating_into_markdown
[extendMarkdown]: #extendmarkdown
[Config Settings]: #configsettings