diff options
| -rwxr-xr-x | docs/writing_extensions.txt | 97 |
1 files changed, 45 insertions, 52 deletions
diff --git a/docs/writing_extensions.txt b/docs/writing_extensions.txt index dbb4dd4..5f0ff01 100755 --- a/docs/writing_extensions.txt +++ b/docs/writing_extensions.txt @@ -10,8 +10,8 @@ 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 [[existing extensions]] -helpful as well. For example, the [[footnote]] extension uses most of the +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][] @@ -152,8 +152,8 @@ There are two types of postprocessors: [ElementTree Postprocessors][] and <h4 id="etpostprocessors">ElementTree Postprocessors</h4> -A ElementTree Postprocessor should inherit from `markdown.Postprocessor` and over-ride -the `run` method which takes one argument `root` and should return either +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: @@ -163,7 +163,8 @@ A pseudo example: #do stufff return my_modified_root -For specifics on manipulating the ElementTree, see [Working with the ElementTree][] below. +For specifics on manipulating the ElementTree, see +[Working with the ElementTree][] below. <h4 id="textpostprocessors">TextPostprocessors</h4> @@ -171,9 +172,9 @@ 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: +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): @@ -182,60 +183,52 @@ to a document: <h3 id="working_with_et">Working with the ElementTree</h3> As mentioned, the Markdown parser converts a source document to an -[ElementTree][] ElementTree object before serializing that back to Unicode text. +[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 of all, to get access to the ElementTree module object you should use: - import markdown - etree = markdown.etree +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 -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][]. +``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. -Example below show basic ElementTree functionality: +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") # 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 + 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 - 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 +You can also manipulate an existing tree. Consider the following example which +adds a ``class`` attribute to all ``a`` elements: -For more information about working with ElementTree visit -ElementTree [official site](http://effbot.org/zone/element-index.htm). + 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 @@ -346,4 +339,4 @@ than one residing in a module. [extendMarkdown]: #extendmarkdown [Config Settings]: #configsettings [makeExtension]: #makeextension - +[ElementTree]: http://effbot.org/zone/element-index.htm |