bee_python 0.0.3 → 0.0.4

data/tools/epydoc/markup/epytext.py

@@ -1,2116 +0,0 @@
-#
-# epytext.py: epydoc formatted docstring parsing
-# Edward Loper
-#
-# Created [04/10/01 12:00 AM]
-# $Id: epytext.py,v 1.1 2009/11/26 13:20:50 casa Exp $
-#
-
-"""
-Parser for epytext strings.  Epytext is a lightweight markup whose
-primary intended application is Python documentation strings.  This
-parser converts Epytext strings to a simple DOM-like representation
-(encoded as a tree of L{Element} objects and strings).  Epytext
-strings can contain the following X{structural blocks}:
-
-    - X{epytext}: The top-level element of the DOM tree.
-    - X{para}: A paragraph of text.  Paragraphs contain no newlines, 
-      and all spaces are soft.
-    - X{section}: A section or subsection.
-    - X{field}: A tagged field.  These fields provide information
-      about specific aspects of a Python object, such as the
-      description of a function's parameter, or the author of a
-      module.
-    - X{literalblock}: A block of literal text.  This text should be
-      displayed as it would be displayed in plaintext.  The
-      parser removes the appropriate amount of leading whitespace 
-      from each line in the literal block.
-    - X{doctestblock}: A block containing sample python code,
-      formatted according to the specifications of the C{doctest}
-      module.
-    - X{ulist}: An unordered list.
-    - X{olist}: An ordered list.
-    - X{li}: A list item.  This tag is used both for unordered list
-      items and for ordered list items.
-
-Additionally, the following X{inline regions} may be used within
-C{para} blocks:
-    
-    - X{code}:   Source code and identifiers.
-    - X{math}:   Mathematical expressions.
-    - X{index}:  A term which should be included in an index, if one
-                 is generated.
-    - X{italic}: Italicized text.
-    - X{bold}:   Bold-faced text.
-    - X{uri}:    A Universal Resource Indicator (URI) or Universal
-                 Resource Locator (URL)
-    - X{link}:   A Python identifier which should be hyperlinked to
-                 the named object's documentation, when possible.
-
-The returned DOM tree will conform to the the following Document Type
-Description::
-
-   <!ENTITY % colorized '(code | math | index | italic |
-                          bold | uri | link | symbol)*'>
-
-   <!ELEMENT epytext ((para | literalblock | doctestblock |
-                      section | ulist | olist)*, fieldlist?)>
-
-   <!ELEMENT para (#PCDATA | %colorized;)*>
-
-   <!ELEMENT section (para | listblock | doctestblock |
-                      section | ulist | olist)+>
-
-   <!ELEMENT fieldlist (field+)>
-   <!ELEMENT field (tag, arg?, (para | listblock | doctestblock)
-                                ulist | olist)+)>
-   <!ELEMENT tag (#PCDATA)>
-   <!ELEMENT arg (#PCDATA)>
-   
-   <!ELEMENT literalblock (#PCDATA | %colorized;)*>
-   <!ELEMENT doctestblock (#PCDATA)>
-
-   <!ELEMENT ulist (li+)>
-   <!ELEMENT olist (li+)>
-   <!ELEMENT li (para | literalblock | doctestblock | ulist | olist)+>
-   <!ATTLIST li bullet NMTOKEN #IMPLIED>
-   <!ATTLIST olist start NMTOKEN #IMPLIED>
-
-   <!ELEMENT uri     (name, target)>
-   <!ELEMENT link    (name, target)>
-   <!ELEMENT name    (#PCDATA | %colorized;)*>
-   <!ELEMENT target  (#PCDATA)>
-   
-   <!ELEMENT code    (#PCDATA | %colorized;)*>
-   <!ELEMENT math    (#PCDATA | %colorized;)*>
-   <!ELEMENT italic  (#PCDATA | %colorized;)*>
-   <!ELEMENT bold    (#PCDATA | %colorized;)*>
-   <!ELEMENT indexed (#PCDATA | %colorized;)>
-   <!ATTLIST code style CDATA #IMPLIED>
-
-   <!ELEMENT symbol (#PCDATA)>
-
-@var SYMBOLS: A list of the of escape symbols that are supported
-      by epydoc.  Currently the following symbols are supported:
-<<<SYMBOLS>>>
-"""
-# Note: the symbol list is appended to the docstring automatically,
-# below.
-
-__docformat__ = 'epytext en'
-
-# Code organization..
-#   1. parse()
-#   2. tokenize()
-#   3. colorize()
-#   4. helpers
-#   5. testing
-
-import re, string, types, sys, os.path
-from epydoc.markup import *
-from epydoc.util import wordwrap, plaintext_to_html, plaintext_to_latex
-from epydoc.markup.doctest import doctest_to_html, doctest_to_latex
-
-##################################################
-## DOM-Like Encoding
-##################################################
-
-class Element:
-    """
-    A very simple DOM-like representation for parsed epytext
-    documents.  Each epytext document is encoded as a tree whose nodes
-    are L{Element} objects, and whose leaves are C{string}s.  Each
-    node is marked by a I{tag} and zero or more I{attributes}.  Each
-    attribute is a mapping from a string key to a string value.
-    """
-    def __init__(self, tag, *children, **attribs):
-        self.tag = tag
-        """A string tag indicating the type of this element.
-        @type: C{string}"""
-        
-        self.children = list(children)
-        """A list of the children of this element.
-        @type: C{list} of (C{string} or C{Element})"""
-        
-        self.attribs = attribs
-        """A dictionary mapping attribute names to attribute values
-        for this element.
-        @type: C{dict} from C{string} to C{string}"""
-
-    def __str__(self):
-        """
-        Return a string representation of this element, using XML
-        notation.
-        @bug: Doesn't escape '<' or '&' or '>'.
-        """
-        attribs = ''.join([' %s=%r' % t for t in self.attribs.items()])
-        return ('<%s%s>' % (self.tag, attribs) +
-                ''.join([str(child) for child in self.children]) +
-                '</%s>' % self.tag)
-
-    def __repr__(self):
-        attribs = ''.join([', %s=%r' % t for t in self.attribs.items()])
-        args = ''.join([', %r' % c for c in self.children])
-        return 'Element(%s%s%s)' % (self.tag, args, attribs)
-
-##################################################
-## Constants
-##################################################
-
-# The possible heading underline characters, listed in order of
-# heading depth. 
-_HEADING_CHARS = "=-~"
-
-# Escape codes.  These should be needed very rarely.
-_ESCAPES = {'lb':'{', 'rb': '}'}
-
-# Symbols.  These can be generated via S{...} escapes.
-SYMBOLS = [
-    # Arrows
-    '<-', '->', '^', 'v', 
-
-    # Greek letters
-    'alpha', 'beta', 'gamma', 'delta', 'epsilon', 'zeta',  
-    'eta', 'theta', 'iota', 'kappa', 'lambda', 'mu',  
-    'nu', 'xi', 'omicron', 'pi', 'rho', 'sigma',  
-    'tau', 'upsilon', 'phi', 'chi', 'psi', 'omega',
-    'Alpha', 'Beta', 'Gamma', 'Delta', 'Epsilon', 'Zeta',  
-    'Eta', 'Theta', 'Iota', 'Kappa', 'Lambda', 'Mu',  
-    'Nu', 'Xi', 'Omicron', 'Pi', 'Rho', 'Sigma',  
-    'Tau', 'Upsilon', 'Phi', 'Chi', 'Psi', 'Omega',
-    
-    # HTML character entities
-    'larr', 'rarr', 'uarr', 'darr', 'harr', 'crarr',
-    'lArr', 'rArr', 'uArr', 'dArr', 'hArr', 
-    'copy', 'times', 'forall', 'exist', 'part',
-    'empty', 'isin', 'notin', 'ni', 'prod', 'sum',
-    'prop', 'infin', 'ang', 'and', 'or', 'cap', 'cup',
-    'int', 'there4', 'sim', 'cong', 'asymp', 'ne',
-    'equiv', 'le', 'ge', 'sub', 'sup', 'nsub',
-    'sube', 'supe', 'oplus', 'otimes', 'perp',
-
-    # Alternate (long) names
-    'infinity', 'integral', 'product',
-    '>=', '<=', 
-    ]
-# Convert to a dictionary, for quick lookup
-_SYMBOLS = {}
-for symbol in SYMBOLS: _SYMBOLS[symbol] = 1
-
-# Add symbols to the docstring.
-symblist = '      '
-symblist += ';\n      '.join([' - C{E{S}{%s}}=S{%s}' % (symbol, symbol)
-                              for symbol in SYMBOLS])
-__doc__ = __doc__.replace('<<<SYMBOLS>>>', symblist)
-del symbol, symblist
-
-# Tags for colorizing text.
-_COLORIZING_TAGS = {
-    'C': 'code',
-    'M': 'math',
-    'X': 'indexed',
-    'I': 'italic', 
-    'B': 'bold',
-    'U': 'uri',
-    'L': 'link',       # A Python identifier that should be linked to 
-    'E': 'escape',     # escapes characters or creates symbols
-    'S': 'symbol',
-    'G': 'graph',
-    }
-
-# Which tags can use "link syntax" (e.g., U{Python<www.python.org>})?
-_LINK_COLORIZING_TAGS = ['link', 'uri']
-
-##################################################
-## Structuring (Top Level)
-##################################################
-
-def parse(str, errors = None):
-    """
-    Return a DOM tree encoding the contents of an epytext string.  Any
-    errors generated during parsing will be stored in C{errors}.
-
-    @param str: The epytext string to parse.
-    @type str: C{string}
-    @param errors: A list where any errors generated during parsing
-        will be stored.  If no list is specified, then fatal errors
-        will generate exceptions, and non-fatal errors will be
-        ignored.
-    @type errors: C{list} of L{ParseError}
-    @return: a DOM tree encoding the contents of an epytext string.
-    @rtype: C{Element}
-    @raise ParseError: If C{errors} is C{None} and an error is
-        encountered while parsing.
-    """
-    # Initialize errors list.
-    if errors == None:
-        errors = []
-        raise_on_error = 1
-    else:
-        raise_on_error = 0
-
-    # Preprocess the string.
-    str = re.sub('\015\012', '\012', str)
-    str = string.expandtabs(str)
-
-    # Tokenize the input string.
-    tokens = _tokenize(str, errors)
-
-    # Have we encountered a field yet?
-    encountered_field = 0
-
-    # Create an document to hold the epytext.
-    doc = Element('epytext')
-
-    # Maintain two parallel stacks: one contains DOM elements, and
-    # gives the ancestors of the current block.  The other contains
-    # indentation values, and gives the indentation of the
-    # corresponding DOM elements.  An indentation of "None" reflects
-    # an unknown indentation.  However, the indentation must be
-    # greater than, or greater than or equal to, the indentation of
-    # the prior element (depending on what type of DOM element it
-    # corresponds to).  No 2 consecutive indent_stack values will be
-    # ever be "None."  Use initial dummy elements in the stack, so we
-    # don't have to worry about bounds checking.
-    stack = [None, doc]
-    indent_stack = [-1, None]
-
-    for token in tokens:
-        # Uncomment this for debugging:
-        #print ('%s: %s\n%s: %s\n' % 
-        #       (''.join(['%-11s' % (t and t.tag) for t in stack]),
-        #        token.tag, ''.join(['%-11s' % i for i in indent_stack]),
-        #        token.indent))
-        
-        # Pop any completed blocks off the stack.
-        _pop_completed_blocks(token, stack, indent_stack)
-
-        # If Token has type PARA, colorize and add the new paragraph
-        if token.tag == Token.PARA:
-            _add_para(doc, token, stack, indent_stack, errors)
-                     
-        # If Token has type HEADING, add the new section
-        elif token.tag == Token.HEADING:
-            _add_section(doc, token, stack, indent_stack, errors)
-
-        # If Token has type LBLOCK, add the new literal block
-        elif token.tag == Token.LBLOCK:
-            stack[-1].children.append(token.to_dom(doc))
-
-        # If Token has type DTBLOCK, add the new doctest block
-        elif token.tag == Token.DTBLOCK:
-            stack[-1].children.append(token.to_dom(doc))
-
-        # If Token has type BULLET, add the new list/list item/field
-        elif token.tag == Token.BULLET:
-            _add_list(doc, token, stack, indent_stack, errors)
-        else:
-            assert 0, 'Unknown token type: '+token.tag
-
-        # Check if the DOM element we just added was a field..
-        if stack[-1].tag == 'field':
-            encountered_field = 1
-        elif encountered_field == 1:
-            if len(stack) <= 3:
-                estr = ("Fields must be the final elements in an "+
-                        "epytext string.")
-                errors.append(StructuringError(estr, token.startline))
-
-    # Graphs use inline markup (G{...}) but are really block-level
-    # elements; so "raise" any graphs we generated.  This is a bit of
-    # a hack, but the alternative is to define a new markup for
-    # block-level elements, which I'd rather not do.  (See sourceforge
-    # bug #1673017.)
-    for child in doc.children:
-        _raise_graphs(child, doc)
-
-    # If there was an error, then signal it!
-    if len([e for e in errors if e.is_fatal()]) > 0:
-        if raise_on_error:
-            raise errors[0]
-        else:
-            return None
-        
-    # Return the top-level epytext DOM element.
-    return doc
-
-def _raise_graphs(tree, parent):
-    # Recurse to children.
-    have_graph_child = False
-    for elt in tree.children:
-        if isinstance(elt, Element):
-            _raise_graphs(elt, tree)
-            if elt.tag == 'graph': have_graph_child = True
-
-    block = ('section', 'fieldlist', 'field', 'ulist', 'olist', 'li')
-    if have_graph_child and tree.tag not in block:
-        child_index = 0
-        for elt in tree.children:
-            if isinstance(elt, Element) and elt.tag == 'graph':
-                # We found a graph: splice it into the parent.
-                parent_index = parent.children.index(tree)
-                left = tree.children[:child_index]
-                right = tree.children[child_index+1:]
-                parent.children[parent_index:parent_index+1] = [
-                    Element(tree.tag, *left, **tree.attribs),
-                    elt,
-                    Element(tree.tag, *right, **tree.attribs)]
-                child_index = 0
-                parent_index += 2
-            else:
-                child_index += 1
-
-def _pop_completed_blocks(token, stack, indent_stack):
-    """
-    Pop any completed blocks off the stack.  This includes any
-    blocks that we have dedented past, as well as any list item
-    blocks that we've dedented to.  The top element on the stack 
-    should only be a list if we're about to start a new list
-    item (i.e., if the next token is a bullet).
-    """
-    indent = token.indent
-    if indent != None:
-        while (len(stack) > 2):
-            pop = 0
-            
-            # Dedent past a block
-            if indent_stack[-1]!=None and indent<indent_stack[-1]: pop=1
-            elif indent_stack[-1]==None and indent<indent_stack[-2]: pop=1
-
-            # Dedent to a list item, if it is follwed by another list
-            # item with the same indentation.
-            elif (token.tag == 'bullet' and indent==indent_stack[-2] and 
-                  stack[-1].tag in ('li', 'field')): pop=1
-
-            # End of a list (no more list items available)
-            elif (stack[-1].tag in ('ulist', 'olist') and
-                  (token.tag != 'bullet' or token.contents[-1] == ':')):
-                pop=1
-
-            # Pop the block, if it's complete.  Otherwise, we're done.
-            if pop == 0: return
-            stack.pop()
-            indent_stack.pop()
-
-def _add_para(doc, para_token, stack, indent_stack, errors):
-    """Colorize the given paragraph, and add it to the DOM tree."""
-    # Check indentation, and update the parent's indentation
-    # when appropriate.
-    if indent_stack[-1] == None:
-        indent_stack[-1] = para_token.indent
-    if para_token.indent == indent_stack[-1]:
-        # Colorize the paragraph and add it.
-        para = _colorize(doc, para_token, errors)
-        if para_token.inline:
-            para.attribs['inline'] = True
-        stack[-1].children.append(para)
-    else:
-        estr = "Improper paragraph indentation."
-        errors.append(StructuringError(estr, para_token.startline))
-
-def _add_section(doc, heading_token, stack, indent_stack, errors):
-    """Add a new section to the DOM tree, with the given heading."""
-    if indent_stack[-1] == None:
-        indent_stack[-1] = heading_token.indent
-    elif indent_stack[-1] != heading_token.indent:
-        estr = "Improper heading indentation."
-        errors.append(StructuringError(estr, heading_token.startline))
-
-    # Check for errors.
-    for tok in stack[2:]:
-        if tok.tag != "section":
-            estr = "Headings must occur at the top level."
-            errors.append(StructuringError(estr, heading_token.startline))
-            break
-    if (heading_token.level+2) > len(stack):
-        estr = "Wrong underline character for heading."
-        errors.append(StructuringError(estr, heading_token.startline))
-
-    # Pop the appropriate number of headings so we're at the
-    # correct level.
-    stack[heading_token.level+2:] = []
-    indent_stack[heading_token.level+2:] = []
-
-    # Colorize the heading
-    head = _colorize(doc, heading_token, errors, 'heading')
-
-    # Add the section's and heading's DOM elements.
-    sec = Element("section")
-    stack[-1].children.append(sec)
-    stack.append(sec)
-    sec.children.append(head)
-    indent_stack.append(None)
-        
-def _add_list(doc, bullet_token, stack, indent_stack, errors):
-    """
-    Add a new list item or field to the DOM tree, with the given
-    bullet or field tag.  When necessary, create the associated
-    list.
-    """
-    # Determine what type of bullet it is.
-    if bullet_token.contents[-1] == '-':
-        list_type = 'ulist'
-    elif bullet_token.contents[-1] == '.':
-        list_type = 'olist'
-    elif bullet_token.contents[-1] == ':':
-        list_type = 'fieldlist'
-    else:
-        raise AssertionError('Bad Bullet: %r' % bullet_token.contents)
-
-    # Is this a new list?
-    newlist = 0
-    if stack[-1].tag != list_type:
-        newlist = 1
-    elif list_type == 'olist' and stack[-1].tag == 'olist':
-        old_listitem = stack[-1].children[-1]
-        old_bullet = old_listitem.attribs.get("bullet").split('.')[:-1]
-        new_bullet = bullet_token.contents.split('.')[:-1]
-        if (new_bullet[:-1] != old_bullet[:-1] or
-            int(new_bullet[-1]) != int(old_bullet[-1])+1):
-            newlist = 1
-
-    # Create the new list.
-    if newlist:
-        if stack[-1].tag is 'fieldlist':
-            # The new list item is not a field list item (since this
-            # is a new list); but it's indented the same as the field
-            # list.  This either means that they forgot to indent the
-            # list, or they are trying to put something after the
-            # field list.  The first one seems more likely, so we'll
-            # just warn about that (to avoid confusion).
-            estr = "Lists must be indented."
-            errors.append(StructuringError(estr, bullet_token.startline))
-        if stack[-1].tag in ('ulist', 'olist', 'fieldlist'):
-            stack.pop()
-            indent_stack.pop()
-
-        if (list_type != 'fieldlist' and indent_stack[-1] is not None and
-            bullet_token.indent == indent_stack[-1]):
-            # Ignore this error if there's text on the same line as
-            # the comment-opening quote -- epydoc can't reliably
-            # determine the indentation for that line.
-            if bullet_token.startline != 1 or bullet_token.indent != 0:
-                estr = "Lists must be indented."
-                errors.append(StructuringError(estr, bullet_token.startline))
-
-        if list_type == 'fieldlist':
-            # Fieldlist should be at the top-level.
-            for tok in stack[2:]:
-                if tok.tag != "section":
-                    estr = "Fields must be at the top level."
-                    errors.append(
-                        StructuringError(estr, bullet_token.startline))
-                    break
-            stack[2:] = []
-            indent_stack[2:] = []
-
-        # Add the new list.
-        lst = Element(list_type)
-        stack[-1].children.append(lst)
-        stack.append(lst)
-        indent_stack.append(bullet_token.indent)
-        if list_type == 'olist':
-            start = bullet_token.contents.split('.')[:-1]
-            if start != '1':
-                lst.attribs["start"] = start[-1]
-
-    # Fields are treated somewhat specially: A "fieldlist"
-    # node is created to make the parsing simpler, but fields
-    # are adjoined directly into the "epytext" node, not into
-    # the "fieldlist" node.
-    if list_type == 'fieldlist':
-        li = Element("field")
-        token_words = bullet_token.contents[1:-1].split(None, 1)
-        tag_elt = Element("tag")
-        tag_elt.children.append(token_words[0])
-        li.children.append(tag_elt)
-
-        if len(token_words) > 1:
-            arg_elt = Element("arg")
-            arg_elt.children.append(token_words[1])
-            li.children.append(arg_elt)
-    else:
-        li = Element("li")
-        if list_type == 'olist':
-            li.attribs["bullet"] = bullet_token.contents
-
-    # Add the bullet.
-    stack[-1].children.append(li)
-    stack.append(li)
-    indent_stack.append(None)
-
-##################################################
-## Tokenization
-##################################################
-
-class Token:
-    """
-    C{Token}s are an intermediate data structure used while
-    constructing the structuring DOM tree for a formatted docstring.
-    There are five types of C{Token}:
-    
-        - Paragraphs
-        - Literal blocks
-        - Doctest blocks
-        - Headings
-        - Bullets
-
-    The text contained in each C{Token} is stored in the
-    C{contents} variable.  The string in this variable has been
-    normalized.  For paragraphs, this means that it has been converted 
-    into a single line of text, with newline/indentation replaced by
-    single spaces.  For literal blocks and doctest blocks, this means
-    that the appropriate amount of leading whitespace has been removed 
-    from each line.
-
-    Each C{Token} has an indentation level associated with it,
-    stored in the C{indent} variable.  This indentation level is used
-    by the structuring procedure to assemble hierarchical blocks.
-
-    @type tag: C{string}
-    @ivar tag: This C{Token}'s type.  Possible values are C{Token.PARA} 
-        (paragraph), C{Token.LBLOCK} (literal block), C{Token.DTBLOCK}
-        (doctest block), C{Token.HEADINGC}, and C{Token.BULLETC}.
-        
-    @type startline: C{int}
-    @ivar startline: The line on which this C{Token} begins.  This 
-        line number is only used for issuing errors.
-
-    @type contents: C{string}
-    @ivar contents: The normalized text contained in this C{Token}.
-    
-    @type indent: C{int} or C{None}
-    @ivar indent: The indentation level of this C{Token} (in
-        number of leading spaces).  A value of C{None} indicates an
-        unknown indentation; this is used for list items and fields
-        that begin with one-line paragraphs.
-        
-    @type level: C{int} or C{None}
-    @ivar level: The heading-level of this C{Token} if it is a
-        heading; C{None}, otherwise.  Valid heading levels are 0, 1,
-        and 2.
-
-    @type inline: C{bool}
-    @ivar inline: If True, the element is an inline level element, comparable
-        to an HTML C{<span>} tag. Else, it is a block level element, comparable
-        to an HTML C{<div>}.
-
-    @type PARA: C{string}
-    @cvar PARA: The C{tag} value for paragraph C{Token}s.
-    @type LBLOCK: C{string}
-    @cvar LBLOCK: The C{tag} value for literal C{Token}s.
-    @type DTBLOCK: C{string}
-    @cvar DTBLOCK: The C{tag} value for doctest C{Token}s.
-    @type HEADING: C{string}
-    @cvar HEADING: The C{tag} value for heading C{Token}s.
-    @type BULLET: C{string}
-    @cvar BULLET: The C{tag} value for bullet C{Token}s.  This C{tag}
-        value is also used for field tag C{Token}s, since fields
-        function syntactically the same as list items.
-    """
-    # The possible token types.
-    PARA = "para"
-    LBLOCK = "literalblock"
-    DTBLOCK = "doctestblock"
-    HEADING = "heading"
-    BULLET = "bullet"
-
-    def __init__(self, tag, startline, contents, indent, level=None,
-                 inline=False):
-        """
-        Create a new C{Token}.
-
-        @param tag: The type of the new C{Token}.
-        @type tag: C{string}
-        @param startline: The line on which the new C{Token} begins.
-        @type startline: C{int}
-        @param contents: The normalized contents of the new C{Token}.
-        @type contents: C{string}
-        @param indent: The indentation of the new C{Token} (in number
-            of leading spaces).  A value of C{None} indicates an
-            unknown indentation.
-        @type indent: C{int} or C{None}
-        @param level: The heading-level of this C{Token} if it is a
-            heading; C{None}, otherwise.
-        @type level: C{int} or C{None}
-        @param inline: Is this C{Token} inline as a C{<span>}?.
-        @type inline: C{bool}
-        """
-        self.tag = tag
-        self.startline = startline
-        self.contents = contents
-        self.indent = indent
-        self.level = level
-        self.inline = inline
-
-    def __repr__(self):
-        """
-        @rtype: C{string}
-        @return: the formal representation of this C{Token}.
-            C{Token}s have formal representaitons of the form:: 
-                <Token: para at line 12>
-        """
-        return '<Token: %s at line %s>' % (self.tag, self.startline)
-
-    def to_dom(self, doc):
-        """
-        @return: a DOM representation of this C{Token}.
-        @rtype: L{Element}
-        """
-        e = Element(self.tag)
-        e.children.append(self.contents)
-        return e
-
-# Construct regular expressions for recognizing bullets.  These are
-# global so they don't have to be reconstructed each time we tokenize
-# a docstring.
-_ULIST_BULLET = '[-]( +|$)'
-_OLIST_BULLET = '(\d+[.])+( +|$)'
-_FIELD_BULLET = '@\w+( [^{}:\n]+)?:'
-_BULLET_RE = re.compile(_ULIST_BULLET + '|' +
-                        _OLIST_BULLET + '|' +
-                        _FIELD_BULLET)
-_LIST_BULLET_RE = re.compile(_ULIST_BULLET + '|' + _OLIST_BULLET)
-_FIELD_BULLET_RE = re.compile(_FIELD_BULLET)
-del _ULIST_BULLET, _OLIST_BULLET, _FIELD_BULLET
-
-def _tokenize_doctest(lines, start, block_indent, tokens, errors):
-    """
-    Construct a L{Token} containing the doctest block starting at
-    C{lines[start]}, and append it to C{tokens}.  C{block_indent}
-    should be the indentation of the doctest block.  Any errors
-    generated while tokenizing the doctest block will be appended to
-    C{errors}.
-
-    @param lines: The list of lines to be tokenized
-    @param start: The index into C{lines} of the first line of the
-        doctest block to be tokenized.
-    @param block_indent: The indentation of C{lines[start]}.  This is
-        the indentation of the doctest block.
-    @param errors: A list where any errors generated during parsing
-        will be stored.  If no list is specified, then errors will 
-        generate exceptions.
-    @return: The line number of the first line following the doctest
-        block.
-        
-    @type lines: C{list} of C{string}
-    @type start: C{int}
-    @type block_indent: C{int}
-    @type tokens: C{list} of L{Token}
-    @type errors: C{list} of L{ParseError}
-    @rtype: C{int}
-    """
-    # If they dedent past block_indent, keep track of the minimum
-    # indentation.  This is used when removing leading indentation
-    # from the lines of the doctest block.
-    min_indent = block_indent
-
-    linenum = start + 1
-    while linenum < len(lines):
-        # Find the indentation of this line.
-        line = lines[linenum]
-        indent = len(line) - len(line.lstrip())
-        
-        # A blank line ends doctest block.
-        if indent == len(line): break
-        
-        # A Dedent past block_indent is an error.
-        if indent < block_indent:
-            min_indent = min(min_indent, indent)
-            estr = 'Improper doctest block indentation.'
-            errors.append(TokenizationError(estr, linenum))
-
-        # Go on to the next line.
-        linenum += 1
-
-    # Add the token, and return the linenum after the token ends.
-    contents = [line[min_indent:] for line in lines[start:linenum]]
-    contents = '\n'.join(contents)
-    tokens.append(Token(Token.DTBLOCK, start, contents, block_indent))
-    return linenum
-
-def _tokenize_literal(lines, start, block_indent, tokens, errors):
-    """
-    Construct a L{Token} containing the literal block starting at
-    C{lines[start]}, and append it to C{tokens}.  C{block_indent}
-    should be the indentation of the literal block.  Any errors
-    generated while tokenizing the literal block will be appended to
-    C{errors}.
-
-    @param lines: The list of lines to be tokenized
-    @param start: The index into C{lines} of the first line of the
-        literal block to be tokenized.
-    @param block_indent: The indentation of C{lines[start]}.  This is
-        the indentation of the literal block.
-    @param errors: A list of the errors generated by parsing.  Any
-        new errors generated while will tokenizing this paragraph
-        will be appended to this list.
-    @return: The line number of the first line following the literal
-        block. 
-        
-    @type lines: C{list} of C{string}
-    @type start: C{int}
-    @type block_indent: C{int}
-    @type tokens: C{list} of L{Token}
-    @type errors: C{list} of L{ParseError}
-    @rtype: C{int}
-    """
-    linenum = start + 1
-    while linenum < len(lines):
-        # Find the indentation of this line.
-        line = lines[linenum]
-        indent = len(line) - len(line.lstrip())
-
-        # A Dedent to block_indent ends the literal block.
-        # (Ignore blank likes, though)
-        if len(line) != indent and indent <= block_indent:
-            break
-        
-        # Go on to the next line.
-        linenum += 1
-
-    # Add the token, and return the linenum after the token ends.
-    contents = [line[block_indent+1:] for line in lines[start:linenum]]
-    contents = '\n'.join(contents)
-    contents = re.sub('(\A[ \n]*\n)|(\n[ \n]*\Z)', '', contents)
-    tokens.append(Token(Token.LBLOCK, start, contents, block_indent))
-    return linenum
-
-def _tokenize_listart(lines, start, bullet_indent, tokens, errors):
-    """
-    Construct L{Token}s for the bullet and the first paragraph of the
-    list item (or field) starting at C{lines[start]}, and append them
-    to C{tokens}.  C{bullet_indent} should be the indentation of the
-    list item.  Any errors generated while tokenizing will be
-    appended to C{errors}.
-
-    @param lines: The list of lines to be tokenized
-    @param start: The index into C{lines} of the first line of the
-        list item to be tokenized.
-    @param bullet_indent: The indentation of C{lines[start]}.  This is
-        the indentation of the list item.
-    @param errors: A list of the errors generated by parsing.  Any
-        new errors generated while will tokenizing this paragraph
-        will be appended to this list.
-    @return: The line number of the first line following the list
-        item's first paragraph.
-        
-    @type lines: C{list} of C{string}
-    @type start: C{int}
-    @type bullet_indent: C{int}
-    @type tokens: C{list} of L{Token}
-    @type errors: C{list} of L{ParseError}
-    @rtype: C{int}
-    """
-    linenum = start + 1
-    para_indent = None
-    doublecolon = lines[start].rstrip()[-2:] == '::'
-
-    # Get the contents of the bullet.
-    para_start = _BULLET_RE.match(lines[start], bullet_indent).end()
-    bcontents = lines[start][bullet_indent:para_start].strip()
-    
-    while linenum < len(lines):
-        # Find the indentation of this line.
-        line = lines[linenum]
-        indent = len(line) - len(line.lstrip())
-
-        # "::" markers end paragraphs.
-        if doublecolon: break
-        if line.rstrip()[-2:] == '::': doublecolon = 1
-
-        # A blank line ends the token
-        if indent == len(line): break
-
-        # Dedenting past bullet_indent ends the list item.
-        if indent < bullet_indent: break
-        
-        # A line beginning with a bullet ends the token.
-        if _BULLET_RE.match(line, indent): break
-        
-        # If this is the second line, set the paragraph indentation, or 
-        # end the token, as appropriate.
-        if para_indent == None: para_indent = indent
-
-        # A change in indentation ends the token
-        if indent != para_indent: break
-
-        # Go on to the next line.
-        linenum += 1
-
-    # Add the bullet token.
-    tokens.append(Token(Token.BULLET, start, bcontents, bullet_indent,
-                        inline=True))
-
-    # Add the paragraph token.
-    pcontents = ([lines[start][para_start:].strip()] + 
-                 [line.strip() for line in lines[start+1:linenum]])
-    pcontents = ' '.join(pcontents).strip()
-    if pcontents:
-        tokens.append(Token(Token.PARA, start, pcontents, para_indent,
-                            inline=True))
-
-    # Return the linenum after the paragraph token ends.
-    return linenum
-
-def _tokenize_para(lines, start, para_indent, tokens, errors):
-    """
-    Construct a L{Token} containing the paragraph starting at
-    C{lines[start]}, and append it to C{tokens}.  C{para_indent}
-    should be the indentation of the paragraph .  Any errors
-    generated while tokenizing the paragraph will be appended to
-    C{errors}.
-
-    @param lines: The list of lines to be tokenized
-    @param start: The index into C{lines} of the first line of the
-        paragraph to be tokenized.
-    @param para_indent: The indentation of C{lines[start]}.  This is
-        the indentation of the paragraph.
-    @param errors: A list of the errors generated by parsing.  Any
-        new errors generated while will tokenizing this paragraph
-        will be appended to this list.
-    @return: The line number of the first line following the
-        paragraph. 
-        
-    @type lines: C{list} of C{string}
-    @type start: C{int}
-    @type para_indent: C{int}
-    @type tokens: C{list} of L{Token}
-    @type errors: C{list} of L{ParseError}
-    @rtype: C{int}
-    """
-    linenum = start + 1
-    doublecolon = 0
-    while linenum < len(lines):
-        # Find the indentation of this line.
-        line = lines[linenum]
-        indent = len(line) - len(line.lstrip())
-
-        # "::" markers end paragraphs.
-        if doublecolon: break
-        if line.rstrip()[-2:] == '::': doublecolon = 1
-
-        # Blank lines end paragraphs
-        if indent == len(line): break
-
-        # Indentation changes end paragraphs
-        if indent != para_indent: break
-
-        # List bullets end paragraphs
-        if _BULLET_RE.match(line, indent): break
-
-        # Check for mal-formatted field items.
-        if line[indent] == '@':
-            estr = "Possible mal-formatted field item."
-            errors.append(TokenizationError(estr, linenum, is_fatal=0))
-            
-        # Go on to the next line.
-        linenum += 1
-
-    contents = [line.strip() for line in lines[start:linenum]]
-    
-    # Does this token look like a heading?
-    if ((len(contents) < 2) or
-        (contents[1][0] not in _HEADING_CHARS) or
-        (abs(len(contents[0])-len(contents[1])) > 5)):
-        looks_like_heading = 0
-    else:
-        looks_like_heading = 1
-        for char in contents[1]:
-            if char != contents[1][0]:
-                looks_like_heading = 0
-                break
-
-    if looks_like_heading:
-        if len(contents[0]) != len(contents[1]):
-            estr = ("Possible heading typo: the number of "+
-                    "underline characters must match the "+
-                    "number of heading characters.")
-            errors.append(TokenizationError(estr, start, is_fatal=0))
-        else:
-            level = _HEADING_CHARS.index(contents[1][0])
-            tokens.append(Token(Token.HEADING, start,
-                                contents[0], para_indent, level))
-            return start+2
-                 
-    # Add the paragraph token, and return the linenum after it ends.
-    contents = ' '.join(contents)
-    tokens.append(Token(Token.PARA, start, contents, para_indent))
-    return linenum
-        
-def _tokenize(str, errors):
-    """
-    Split a given formatted docstring into an ordered list of
-    C{Token}s, according to the epytext markup rules.
-
-    @param str: The epytext string
-    @type str: C{string}
-    @param errors: A list where any errors generated during parsing
-        will be stored.  If no list is specified, then errors will 
-        generate exceptions.
-    @type errors: C{list} of L{ParseError}
-    @return: a list of the C{Token}s that make up the given string.
-    @rtype: C{list} of L{Token}
-    """
-    tokens = []
-    lines = str.split('\n')
-
-    # Scan through the lines, determining what @type of token we're
-    # dealing with, and tokenizing it, as appropriate.
-    linenum = 0
-    while linenum < len(lines):
-        # Get the current line and its indentation.
-        line = lines[linenum]
-        indent = len(line)-len(line.lstrip())
-
-        if indent == len(line):
-            # Ignore blank lines.
-            linenum += 1
-            continue
-        elif line[indent:indent+4] == '>>> ':
-            # blocks starting with ">>> " are doctest block tokens.
-            linenum = _tokenize_doctest(lines, linenum, indent,
-                                        tokens, errors)
-        elif _BULLET_RE.match(line, indent):
-            # blocks starting with a bullet are LI start tokens.
-            linenum = _tokenize_listart(lines, linenum, indent,
-                                        tokens, errors)
-            if tokens[-1].indent != None:
-                indent = tokens[-1].indent
-        else:
-            # Check for mal-formatted field items.
-            if line[indent] == '@':
-                estr = "Possible mal-formatted field item."
-                errors.append(TokenizationError(estr, linenum, is_fatal=0))
-            
-            # anything else is either a paragraph or a heading.
-            linenum = _tokenize_para(lines, linenum, indent, tokens, errors)
-
-        # Paragraph tokens ending in '::' initiate literal blocks.
-        if (tokens[-1].tag == Token.PARA and
-            tokens[-1].contents[-2:] == '::'):
-            tokens[-1].contents = tokens[-1].contents[:-1]
-            linenum = _tokenize_literal(lines, linenum, indent, tokens, errors)
-
-    return tokens
-
-
-##################################################
-## Inline markup ("colorizing")
-##################################################
-
-# Assorted regular expressions used for colorizing.
-_BRACE_RE = re.compile('{|}')
-_TARGET_RE = re.compile('^(.*?)\s*<(?:URI:|URL:)?([^<>]+)>$')
-
-def _colorize(doc, token, errors, tagName='para'):
-    """
-    Given a string containing the contents of a paragraph, produce a
-    DOM C{Element} encoding that paragraph.  Colorized regions are
-    represented using DOM C{Element}s, and text is represented using
-    DOM C{Text}s.
-
-    @param errors: A list of errors.  Any newly generated errors will
-        be appended to this list.
-    @type errors: C{list} of C{string}
-    
-    @param tagName: The element tag for the DOM C{Element} that should
-        be generated.
-    @type tagName: C{string}
-    
-    @return: a DOM C{Element} encoding the given paragraph.
-    @returntype: C{Element}
-    """
-    str = token.contents
-    linenum = 0
-    
-    # Maintain a stack of DOM elements, containing the ancestors of
-    # the text currently being analyzed.  New elements are pushed when 
-    # "{" is encountered, and old elements are popped when "}" is
-    # encountered. 
-    stack = [Element(tagName)]
-
-    # This is just used to make error-reporting friendlier.  It's a
-    # stack parallel to "stack" containing the index of each element's 
-    # open brace.
-    openbrace_stack = [0]
-
-    # Process the string, scanning for '{' and '}'s.  start is the
-    # index of the first unprocessed character.  Each time through the
-    # loop, we process the text from the first unprocessed character
-    # to the next open or close brace.
-    start = 0
-    while 1:
-        match = _BRACE_RE.search(str, start)
-        if match == None: break
-        end = match.start()
-        
-        # Open braces start new colorizing elements.  When preceeded
-        # by a capital letter, they specify a colored region, as
-        # defined by the _COLORIZING_TAGS dictionary.  Otherwise, 
-        # use a special "literal braces" element (with tag "litbrace"),
-        # and convert them to literal braces once we find the matching 
-        # close-brace.
-        if match.group() == '{':
-            if (end>0) and 'A' <= str[end-1] <= 'Z':
-                if (end-1) > start:
-                    stack[-1].children.append(str[start:end-1])
-                if str[end-1] not in _COLORIZING_TAGS:
-                    estr = "Unknown inline markup tag."
-                    errors.append(ColorizingError(estr, token, end-1))
-                    stack.append(Element('unknown'))
-                else:
-                    tag = _COLORIZING_TAGS[str[end-1]]
-                    stack.append(Element(tag))
-            else:
-                if end > start:
-                    stack[-1].children.append(str[start:end])
-                stack.append(Element('litbrace'))
-            openbrace_stack.append(end)
-            stack[-2].children.append(stack[-1])
-            
-        # Close braces end colorizing elements.
-        elif match.group() == '}':
-            # Check for (and ignore) unbalanced braces.
-            if len(stack) <= 1:
-                estr = "Unbalanced '}'."
-                errors.append(ColorizingError(estr, token, end))
-                start = end + 1
-                continue
-
-            # Add any remaining text.
-            if end > start:
-                stack[-1].children.append(str[start:end])
-
-            # Special handling for symbols:
-            if stack[-1].tag == 'symbol':
-                if (len(stack[-1].children) != 1 or
-                    not isinstance(stack[-1].children[0], basestring)):
-                    estr = "Invalid symbol code."
-                    errors.append(ColorizingError(estr, token, end))
-                else:
-                    symb = stack[-1].children[0]
-                    if symb in _SYMBOLS:
-                        # It's a symbol
-                        stack[-2].children[-1] = Element('symbol', symb)
-                    else:
-                        estr = "Invalid symbol code."
-                        errors.append(ColorizingError(estr, token, end))
-                        
-            # Special handling for escape elements:
-            if stack[-1].tag == 'escape':
-                if (len(stack[-1].children) != 1 or
-                    not isinstance(stack[-1].children[0], basestring)):
-                    estr = "Invalid escape code."
-                    errors.append(ColorizingError(estr, token, end))
-                else:
-                    escp = stack[-1].children[0]
-                    if escp in _ESCAPES:
-                        # It's an escape from _ESCPAES
-                        stack[-2].children[-1] = _ESCAPES[escp]
-                    elif len(escp) == 1:
-                        # It's a single-character escape (eg E{.})
-                        stack[-2].children[-1] = escp
-                    else:
-                        estr = "Invalid escape code."
-                        errors.append(ColorizingError(estr, token, end))
-
-            # Special handling for literal braces elements:
-            if stack[-1].tag == 'litbrace':
-                stack[-2].children[-1:] = ['{'] + stack[-1].children + ['}']
-
-            # Special handling for graphs:
-            if stack[-1].tag == 'graph':
-                _colorize_graph(doc, stack[-1], token, end, errors)
-
-            # Special handling for link-type elements:
-            if stack[-1].tag in _LINK_COLORIZING_TAGS:
-                _colorize_link(doc, stack[-1], token, end, errors)
-
-            # Pop the completed element.
-            openbrace_stack.pop()
-            stack.pop()
-
-        start = end+1
-
-    # Add any final text.
-    if start < len(str):
-        stack[-1].children.append(str[start:])
-        
-    if len(stack) != 1: 
-        estr = "Unbalanced '{'."
-        errors.append(ColorizingError(estr, token, openbrace_stack[-1]))
-
-    return stack[0]
-
-GRAPH_TYPES = ['classtree', 'packagetree', 'importgraph', 'callgraph']
-
-def _colorize_graph(doc, graph, token, end, errors):
-    """
-    Eg::
-      G{classtree}
-      G{classtree x, y, z}
-      G{importgraph}
-    """
-    bad_graph_spec = False
-    
-    children = graph.children[:]
-    graph.children = []
-
-    if len(children) != 1 or not isinstance(children[0], basestring):
-        bad_graph_spec = "Bad graph specification"
-    else:
-        pieces = children[0].split(None, 1)
-        graphtype = pieces[0].replace(':','').strip().lower()
-        if graphtype in GRAPH_TYPES:
-            if len(pieces) == 2:
-                if re.match(r'\s*:?\s*([\w\.]+\s*,?\s*)*', pieces[1]):
-                    args = pieces[1].replace(',', ' ').replace(':','').split()
-                else:
-                    bad_graph_spec = "Bad graph arg list"
-            else:
-                args = []
-        else:
-            bad_graph_spec = ("Bad graph type %s -- use one of %s" %
-                              (pieces[0], ', '.join(GRAPH_TYPES)))
-
-    if bad_graph_spec:
-        errors.append(ColorizingError(bad_graph_spec, token, end))
-        graph.children.append('none')
-        graph.children.append('')
-        return
-
-    graph.children.append(graphtype)
-    for arg in args:
-        graph.children.append(arg)
-
-def _colorize_link(doc, link, token, end, errors):
-    variables = link.children[:]
-
-    # If the last child isn't text, we know it's bad.
-    if len(variables)==0 or not isinstance(variables[-1], basestring):
-        estr = "Bad %s target." % link.tag
-        errors.append(ColorizingError(estr, token, end))
-        return
-    
-    # Did they provide an explicit target?
-    match2 = _TARGET_RE.match(variables[-1])
-    if match2:
-        (text, target) = match2.groups()
-        variables[-1] = text
-    # Can we extract an implicit target?
-    elif len(variables) == 1:
-        target = variables[0]
-    else:
-        estr = "Bad %s target." % link.tag
-        errors.append(ColorizingError(estr, token, end))
-        return
-
-    # Construct the name element.
-    name_elt = Element('name', *variables)
-
-    # Clean up the target.  For URIs, assume http or mailto if they
-    # don't specify (no relative urls)
-    target = re.sub(r'\s', '', target)
-    if link.tag=='uri':
-        if not re.match(r'\w+:', target):
-            if re.match(r'\w+@(\w+)(\.\w+)*', target):
-                target = 'mailto:' + target
-            else:
-                target = 'http://'+target
-    elif link.tag=='link':
-        # Remove arg lists for functions (e.g., L{_colorize_link()})
-        target = re.sub(r'\(.*\)$', '', target)
-        if not re.match(r'^[a-zA-Z_]\w*(\.[a-zA-Z_]\w*)*$', target):
-            estr = "Bad link target."
-            errors.append(ColorizingError(estr, token, end))
-            return
-
-    # Construct the target element.
-    target_elt = Element('target', target)
-
-    # Add them to the link element.
-    link.children = [name_elt, target_elt]
-
-##################################################
-## Formatters
-##################################################
-
-def to_epytext(tree, indent=0, seclevel=0):
-    """
-    Convert a DOM document encoding epytext back to an epytext string.
-    This is the inverse operation from L{parse}.  I.e., assuming there
-    are no errors, the following is true:
-        - C{parse(to_epytext(tree)) == tree}
-
-    The inverse is true, except that whitespace, line wrapping, and
-    character escaping may be done differently.
-        - C{to_epytext(parse(str)) == str} (approximately)
-
-    @param tree: A DOM document encoding of an epytext string.
-    @type tree: C{Element}
-    @param indent: The indentation for the string representation of
-        C{tree}.  Each line of the returned string will begin with
-        C{indent} space characters.
-    @type indent: C{int}
-    @param seclevel: The section level that C{tree} appears at.  This
-        is used to generate section headings.
-    @type seclevel: C{int}
-    @return: The epytext string corresponding to C{tree}.
-    @rtype: C{string}
-    """
-    if isinstance(tree, basestring):
-        str = re.sub(r'\{', '\0', tree)
-        str = re.sub(r'\}', '\1', str)
-        return str
-
-    if tree.tag == 'epytext': indent -= 2
-    if tree.tag == 'section': seclevel += 1
-    variables = [to_epytext(c, indent+2, seclevel) for c in tree.children]
-    childstr = ''.join(variables)
-
-    # Clean up for literal blocks (add the double "::" back)
-    childstr = re.sub(':(\s*)\2', '::\\1', childstr)
-
-    if tree.tag == 'para':
-        str = wordwrap(childstr, indent)+'\n'
-        str = re.sub(r'((^|\n)\s*\d+)\.', r'\1E{.}', str)
-        str = re.sub(r'((^|\n)\s*)-', r'\1E{-}', str)
-        str = re.sub(r'((^|\n)\s*)@', r'\1E{@}', str)
-        str = re.sub(r'::(\s*($|\n))', r'E{:}E{:}\1', str)
-        str = re.sub('\0', 'E{lb}', str)
-        str = re.sub('\1', 'E{rb}', str)
-        return str
-    elif tree.tag == 'li':
-        bullet = tree.attribs.get('bullet') or '-'
-        return indent*' '+ bullet + ' ' + childstr.lstrip()
-    elif tree.tag == 'heading':
-        str = re.sub('\0', 'E{lb}',childstr)
-        str = re.sub('\1', 'E{rb}', str)
-        uline = len(childstr)*_HEADING_CHARS[seclevel-1]
-        return (indent-2)*' ' + str + '\n' + (indent-2)*' '+uline+'\n'
-    elif tree.tag == 'doctestblock':
-        str = re.sub('\0', '{', childstr)
-        str = re.sub('\1', '}', str)
-        lines = ['  '+indent*' '+line for line in str.split('\n')]
-        return '\n'.join(lines) + '\n\n'
-    elif tree.tag == 'literalblock':
-        str = re.sub('\0', '{', childstr)
-        str = re.sub('\1', '}', str)
-        lines = [(indent+1)*' '+line for line in str.split('\n')]
-        return '\2' + '\n'.join(lines) + '\n\n'
-    elif tree.tag == 'field':
-        numargs = 0
-        while tree.children[numargs+1].tag == 'arg': numargs += 1
-        tag = variables[0]
-        args = variables[1:1+numargs]
-        body = variables[1+numargs:]
-        str = (indent)*' '+'@'+variables[0]
-        if args: str += '(' + ', '.join(args) + ')'
-        return str + ':\n' + ''.join(body)
-    elif tree.tag == 'target':
-        return '<%s>' % childstr
-    elif tree.tag in ('fieldlist', 'tag', 'arg', 'epytext',
-                          'section', 'olist', 'ulist', 'name'):
-        return childstr
-    elif tree.tag == 'symbol':
-        return 'E{%s}' % childstr
-    elif tree.tag == 'graph':
-        return 'G{%s}' % ' '.join(variables)
-    else:
-        for (tag, name) in _COLORIZING_TAGS.items():
-            if name == tree.tag:
-                return '%s{%s}' % (tag, childstr)
-    raise ValueError('Unknown DOM element %r' % tree.tag)
-
-SYMBOL_TO_PLAINTEXT = {
-    'crarr': '\\',
-    }
-
-def to_plaintext(tree, indent=0, seclevel=0):
-    """    
-    Convert a DOM document encoding epytext to a string representation.
-    This representation is similar to the string generated by
-    C{to_epytext}, but C{to_plaintext} removes inline markup, prints
-    escaped characters in unescaped form, etc.
-
-    @param tree: A DOM document encoding of an epytext string.
-    @type tree: C{Element}
-    @param indent: The indentation for the string representation of
-        C{tree}.  Each line of the returned string will begin with
-        C{indent} space characters.
-    @type indent: C{int}
-    @param seclevel: The section level that C{tree} appears at.  This
-        is used to generate section headings.
-    @type seclevel: C{int}
-    @return: The epytext string corresponding to C{tree}.
-    @rtype: C{string}
-    """
-    if isinstance(tree, basestring): return tree
-
-    if tree.tag == 'section': seclevel += 1
-
-    # Figure out the child indent level.
-    if tree.tag == 'epytext': cindent = indent
-    elif tree.tag == 'li' and tree.attribs.get('bullet'):
-        cindent = indent + 1 + len(tree.attribs.get('bullet'))
-    else:
-        cindent = indent + 2
-    variables = [to_plaintext(c, cindent, seclevel) for c in tree.children]
-    childstr = ''.join(variables)
-
-    if tree.tag == 'para':
-        return wordwrap(childstr, indent)+'\n'
-    elif tree.tag == 'li':
-        # We should be able to use getAttribute here; but there's no
-        # convenient way to test if an element has an attribute..
-        bullet = tree.attribs.get('bullet') or '-'
-        return indent*' ' + bullet + ' ' + childstr.lstrip()
-    elif tree.tag == 'heading':
-        uline = len(childstr)*_HEADING_CHARS[seclevel-1]
-        return ((indent-2)*' ' + childstr + '\n' +
-                (indent-2)*' ' + uline + '\n')
-    elif tree.tag == 'doctestblock':
-        lines = [(indent+2)*' '+line for line in childstr.split('\n')]
-        return '\n'.join(lines) + '\n\n'
-    elif tree.tag == 'literalblock':
-        lines = [(indent+1)*' '+line for line in childstr.split('\n')]
-        return '\n'.join(lines) + '\n\n'
-    elif tree.tag == 'fieldlist':
-        return childstr
-    elif tree.tag == 'field':
-        numargs = 0
-        while tree.children[numargs+1].tag == 'arg': numargs += 1
-        tag = variables[0]
-        args = variables[1:1+numargs]
-        body = variables[1+numargs:]
-        str = (indent)*' '+'@'+variables[0]
-        if args: str += '(' + ', '.join(args) + ')'
-        return str + ':\n' + ''.join(body)
-    elif tree.tag == 'uri':
-        if len(variables) != 2: raise ValueError('Bad URI ')
-        elif variables[0] == variables[1]: return '<%s>' % variables[1]
-        else: return '%r<%s>' % (variables[0], variables[1])
-    elif tree.tag == 'link':
-        if len(variables) != 2: raise ValueError('Bad Link')
-        return '%s' % variables[0]
-    elif tree.tag in ('olist', 'ulist'):
-        # [xx] always use condensed lists.
-        ## Use a condensed list if each list item is 1 line long.
-        #for child in variables:
-        #    if child.count('\n') > 2: return childstr
-        return childstr.replace('\n\n', '\n')+'\n'
-    elif tree.tag == 'symbol':
-        return '%s' % SYMBOL_TO_PLAINTEXT.get(childstr, childstr)
-    elif tree.tag == 'graph':
-        return '<<%s graph: %s>>' % (variables[0], ', '.join(variables[1:]))
-    else:
-        # Assume that anything else can be passed through.
-        return childstr
-
-def to_debug(tree, indent=4, seclevel=0):
-    """    
-    Convert a DOM document encoding epytext back to an epytext string,
-    annotated with extra debugging information.  This function is
-    similar to L{to_epytext}, but it adds explicit information about
-    where different blocks begin, along the left margin.
-
-    @param tree: A DOM document encoding of an epytext string.
-    @type tree: C{Element}
-    @param indent: The indentation for the string representation of
-        C{tree}.  Each line of the returned string will begin with
-        C{indent} space characters.
-    @type indent: C{int}
-    @param seclevel: The section level that C{tree} appears at.  This
-        is used to generate section headings.
-    @type seclevel: C{int}
-    @return: The epytext string corresponding to C{tree}.
-    @rtype: C{string}
-    """
-    if isinstance(tree, basestring):
-        str = re.sub(r'\{', '\0', tree)
-        str = re.sub(r'\}', '\1', str)
-        return str
-
-    if tree.tag == 'section': seclevel += 1
-    variables = [to_debug(c, indent+2, seclevel) for c in tree.children]
-    childstr = ''.join(variables)
-
-    # Clean up for literal blocks (add the double "::" back)
-    childstr = re.sub(':( *\n     \|\n)\2', '::\\1', childstr)
-
-    if tree.tag == 'para':
-        str = wordwrap(childstr, indent-6, 69)+'\n'
-        str = re.sub(r'((^|\n)\s*\d+)\.', r'\1E{.}', str)
-        str = re.sub(r'((^|\n)\s*)-', r'\1E{-}', str)
-        str = re.sub(r'((^|\n)\s*)@', r'\1E{@}', str)
-        str = re.sub(r'::(\s*($|\n))', r'E{:}E{:}\1', str)
-        str = re.sub('\0', 'E{lb}', str)
-        str = re.sub('\1', 'E{rb}', str)
-        lines = str.rstrip().split('\n')
-        lines[0] = '   P>|' + lines[0]
-        lines[1:] = ['     |'+l for l in lines[1:]]
-        return '\n'.join(lines)+'\n     |\n'
-    elif tree.tag == 'li':
-        bullet = tree.attribs.get('bullet') or '-'
-        return '  LI>|'+ (indent-6)*' '+ bullet + ' ' + childstr[6:].lstrip()
-    elif tree.tag in ('olist', 'ulist'):
-        return 'LIST>|'+(indent-4)*' '+childstr[indent+2:]
-    elif tree.tag == 'heading':
-        str = re.sub('\0', 'E{lb}', childstr)
-        str = re.sub('\1', 'E{rb}', str)
-        uline = len(childstr)*_HEADING_CHARS[seclevel-1]
-        return ('SEC'+`seclevel`+'>|'+(indent-8)*' ' + str + '\n' +
-                '     |'+(indent-8)*' ' + uline + '\n')
-    elif tree.tag == 'doctestblock':
-        str = re.sub('\0', '{', childstr)
-        str = re.sub('\1', '}', str)
-        lines = ['     |'+(indent-4)*' '+line for line in str.split('\n')]
-        lines[0] = 'DTST>'+lines[0][5:]
-        return '\n'.join(lines) + '\n     |\n'
-    elif tree.tag == 'literalblock':
-        str = re.sub('\0', '{', childstr)
-        str = re.sub('\1', '}', str)
-        lines = ['     |'+(indent-5)*' '+line for line in str.split('\n')]
-        lines[0] = ' LIT>'+lines[0][5:]
-        return '\2' + '\n'.join(lines) + '\n     |\n'
-    elif tree.tag == 'field':
-        numargs = 0
-        while tree.children[numargs+1].tag == 'arg': numargs += 1
-        tag = variables[0]
-        args = variables[1:1+numargs]
-        body = variables[1+numargs:]
-        str = ' FLD>|'+(indent-6)*' '+'@'+variables[0]
-        if args: str += '(' + ', '.join(args) + ')'
-        return str + ':\n' + ''.join(body)
-    elif tree.tag == 'target':
-        return '<%s>' % childstr
-    elif tree.tag in ('fieldlist', 'tag', 'arg', 'epytext',
-                          'section', 'olist', 'ulist', 'name'):
-        return childstr
-    elif tree.tag == 'symbol':
-        return 'E{%s}' % childstr
-    elif tree.tag == 'graph':
-        return 'G{%s}' % ' '.join(variables)
-    else:
-        for (tag, name) in _COLORIZING_TAGS.items():
-            if name == tree.tag:
-                return '%s{%s}' % (tag, childstr)
-    raise ValueError('Unknown DOM element %r' % tree.tag)
-
-##################################################
-## Top-Level Wrapper function
-##################################################
-def pparse(str, show_warnings=1, show_errors=1, stream=sys.stderr):
-    """
-    Pretty-parse the string.  This parses the string, and catches any
-    warnings or errors produced.  Any warnings and errors are
-    displayed, and the resulting DOM parse structure is returned.
-
-    @param str: The string to parse.
-    @type str: C{string}
-    @param show_warnings: Whether or not to display non-fatal errors
-        generated by parsing C{str}.
-    @type show_warnings: C{boolean}
-    @param show_errors: Whether or not to display fatal errors 
-        generated by parsing C{str}.
-    @type show_errors: C{boolean}
-    @param stream: The stream that warnings and errors should be
-        written to.
-    @type stream: C{stream}
-    @return: a DOM document encoding the contents of C{str}.
-    @rtype: C{Element}
-    @raise SyntaxError: If any fatal errors were encountered.
-    """
-    errors = []
-    confused = 0
-    try:
-        val = parse(str, errors)
-        warnings = [e for e in errors if not e.is_fatal()]
-        errors = [e for e in errors if e.is_fatal()]
-    except:
-        confused = 1
-        
-    if not show_warnings: warnings = []
-    warnings.sort()
-    errors.sort()
-    if warnings:
-        print >>stream, '='*SCRWIDTH
-        print >>stream, "WARNINGS"
-        print >>stream, '-'*SCRWIDTH
-        for warning in warnings:
-            print >>stream, warning.as_warning()
-        print >>stream, '='*SCRWIDTH
-    if errors and show_errors:
-        if not warnings: print >>stream, '='*SCRWIDTH
-        print >>stream, "ERRORS"
-        print >>stream, '-'*SCRWIDTH
-        for error in errors:
-            print >>stream, error
-        print >>stream, '='*SCRWIDTH
-
-    if confused: raise
-    elif errors: raise SyntaxError('Encountered Errors')
-    else: return val
-
-##################################################
-## Parse Errors
-##################################################
-
-class TokenizationError(ParseError):
-    """
-    An error generated while tokenizing a formatted documentation
-    string.
-    """
-
-class StructuringError(ParseError):
-    """
-    An error generated while structuring a formatted documentation
-    string.
-    """
-
-class ColorizingError(ParseError):
-    """
-    An error generated while colorizing a paragraph.
-    """
-    def __init__(self, descr, token, charnum, is_fatal=1):
-        """
-        Construct a new colorizing exception.
-        
-        @param descr: A short description of the error.
-        @type descr: C{string}
-        @param token: The token where the error occured
-        @type token: L{Token}
-        @param charnum: The character index of the position in
-            C{token} where the error occured.
-        @type charnum: C{int}
-        """
-        ParseError.__init__(self, descr, token.startline, is_fatal)
-        self.token = token
-        self.charnum = charnum
-
-    CONTEXT_RANGE = 20
-    def descr(self):
-        RANGE = self.CONTEXT_RANGE
-        if self.charnum <= RANGE:
-            left = self.token.contents[0:self.charnum]
-        else:
-            left = '...'+self.token.contents[self.charnum-RANGE:self.charnum]
-        if (len(self.token.contents)-self.charnum) <= RANGE:
-            right = self.token.contents[self.charnum:]
-        else:
-            right = (self.token.contents[self.charnum:self.charnum+RANGE]
-                     + '...')
-        return ('%s\n\n%s%s\n%s^' % (self._descr, left, right, ' '*len(left)))
-                
-##################################################
-## Convenience parsers
-##################################################
-
-def parse_as_literal(str):
-    """
-    Return a DOM document matching the epytext DTD, containing a
-    single literal block.  That literal block will include the
-    contents of the given string.  This method is typically used as a
-    fall-back when the parser fails.
-
-    @param str: The string which should be enclosed in a literal
-        block.
-    @type str: C{string}
-    
-    @return: A DOM document containing C{str} in a single literal
-        block.
-    @rtype: C{Element}
-    """
-    return Element('epytext', Element('literalblock', str))
-
-def parse_as_para(str):
-    """
-    Return a DOM document matching the epytext DTD, containing a
-    single paragraph.  That paragraph will include the contents of the
-    given string.  This can be used to wrap some forms of
-    automatically generated information (such as type names) in
-    paragraphs.
-
-    @param str: The string which should be enclosed in a paragraph.
-    @type str: C{string}
-    
-    @return: A DOM document containing C{str} in a single paragraph.
-    @rtype: C{Element}
-    """
-    return Element('epytext', Element('para', str))
-
-#################################################################
-##                    SUPPORT FOR EPYDOC
-#################################################################
-
-def parse_docstring(docstring, errors, **options):
-    """
-    Parse the given docstring, which is formatted using epytext; and
-    return a C{ParsedDocstring} representation of its contents.
-    @param docstring: The docstring to parse
-    @type docstring: C{string}
-    @param errors: A list where any errors generated during parsing
-        will be stored.
-    @type errors: C{list} of L{ParseError}
-    @param options: Extra options.  Unknown options are ignored.
-        Currently, no extra options are defined.
-    @rtype: L{ParsedDocstring}
-    """
-    return ParsedEpytextDocstring(parse(docstring, errors), **options)
-    
-class ParsedEpytextDocstring(ParsedDocstring):
-    SYMBOL_TO_HTML = {
-        # Symbols
-        '<-': '&larr;', '->': '&rarr;', '^': '&uarr;', 'v': '&darr;',
-    
-        # Greek letters
-        'alpha': '&alpha;', 'beta': '&beta;', 'gamma': '&gamma;',
-        'delta': '&delta;', 'epsilon': '&epsilon;', 'zeta': '&zeta;',  
-        'eta': '&eta;', 'theta': '&theta;', 'iota': '&iota;', 
-        'kappa': '&kappa;', 'lambda': '&lambda;', 'mu': '&mu;',  
-        'nu': '&nu;', 'xi': '&xi;', 'omicron': '&omicron;',  
-        'pi': '&pi;', 'rho': '&rho;', 'sigma': '&sigma;',  
-        'tau': '&tau;', 'upsilon': '&upsilon;', 'phi': '&phi;',  
-        'chi': '&chi;', 'psi': '&psi;', 'omega': '&omega;',
-        'Alpha': '&Alpha;', 'Beta': '&Beta;', 'Gamma': '&Gamma;',
-        'Delta': '&Delta;', 'Epsilon': '&Epsilon;', 'Zeta': '&Zeta;',  
-        'Eta': '&Eta;', 'Theta': '&Theta;', 'Iota': '&Iota;', 
-        'Kappa': '&Kappa;', 'Lambda': '&Lambda;', 'Mu': '&Mu;',  
-        'Nu': '&Nu;', 'Xi': '&Xi;', 'Omicron': '&Omicron;',  
-        'Pi': '&Pi;', 'Rho': '&Rho;', 'Sigma': '&Sigma;',  
-        'Tau': '&Tau;', 'Upsilon': '&Upsilon;', 'Phi': '&Phi;',  
-        'Chi': '&Chi;', 'Psi': '&Psi;', 'Omega': '&Omega;',
-    
-        # HTML character entities
-        'larr': '&larr;', 'rarr': '&rarr;', 'uarr': '&uarr;',
-        'darr': '&darr;', 'harr': '&harr;', 'crarr': '&crarr;',
-        'lArr': '&lArr;', 'rArr': '&rArr;', 'uArr': '&uArr;',
-        'dArr': '&dArr;', 'hArr': '&hArr;', 
-        'copy': '&copy;', 'times': '&times;', 'forall': '&forall;',
-        'exist': '&exist;', 'part': '&part;',
-        'empty': '&empty;', 'isin': '&isin;', 'notin': '&notin;',
-        'ni': '&ni;', 'prod': '&prod;', 'sum': '&sum;',
-        'prop': '&prop;', 'infin': '&infin;', 'ang': '&ang;',
-        'and': '&and;', 'or': '&or;', 'cap': '&cap;', 'cup': '&cup;',
-        'int': '&int;', 'there4': '&there4;', 'sim': '&sim;',
-        'cong': '&cong;', 'asymp': '&asymp;', 'ne': '&ne;',
-        'equiv': '&equiv;', 'le': '&le;', 'ge': '&ge;',
-        'sub': '&sub;', 'sup': '&sup;', 'nsub': '&nsub;',
-        'sube': '&sube;', 'supe': '&supe;', 'oplus': '&oplus;',
-        'otimes': '&otimes;', 'perp': '&perp;',
-    
-        # Alternate (long) names
-        'infinity': '&infin;', 'integral': '&int;', 'product': '&prod;',
-        '<=': '&le;', '>=': '&ge;',
-        }
-    
-    SYMBOL_TO_LATEX = {
-        # Symbols
-        '<-': r'\(\leftarrow\)', '->': r'\(\rightarrow\)',
-        '^': r'\(\uparrow\)', 'v': r'\(\downarrow\)',
-    
-        # Greek letters (use lower case when upcase not available)
-
-        'alpha': r'\(\alpha\)', 'beta': r'\(\beta\)', 'gamma':
-        r'\(\gamma\)', 'delta': r'\(\delta\)', 'epsilon':
-        r'\(\epsilon\)', 'zeta': r'\(\zeta\)', 'eta': r'\(\eta\)',
-        'theta': r'\(\theta\)', 'iota': r'\(\iota\)', 'kappa':
-        r'\(\kappa\)', 'lambda': r'\(\lambda\)', 'mu': r'\(\mu\)',
-        'nu': r'\(\nu\)', 'xi': r'\(\xi\)', 'omicron': r'\(o\)', 'pi':
-        r'\(\pi\)', 'rho': r'\(\rho\)', 'sigma': r'\(\sigma\)', 'tau':
-        r'\(\tau\)', 'upsilon': r'\(\upsilon\)', 'phi': r'\(\phi\)',
-        'chi': r'\(\chi\)', 'psi': r'\(\psi\)', 'omega':
-        r'\(\omega\)',
-        
-        'Alpha': r'\(\alpha\)', 'Beta': r'\(\beta\)', 'Gamma':
-        r'\(\Gamma\)', 'Delta': r'\(\Delta\)', 'Epsilon':
-        r'\(\epsilon\)', 'Zeta': r'\(\zeta\)', 'Eta': r'\(\eta\)',
-        'Theta': r'\(\Theta\)', 'Iota': r'\(\iota\)', 'Kappa':
-        r'\(\kappa\)', 'Lambda': r'\(\Lambda\)', 'Mu': r'\(\mu\)',
-        'Nu': r'\(\nu\)', 'Xi': r'\(\Xi\)', 'Omicron': r'\(o\)', 'Pi':
-        r'\(\Pi\)', 'ho': r'\(\rho\)', 'Sigma': r'\(\Sigma\)', 'Tau':
-        r'\(\tau\)', 'Upsilon': r'\(\Upsilon\)', 'Phi': r'\(\Phi\)',
-        'Chi': r'\(\chi\)', 'Psi': r'\(\Psi\)', 'Omega':
-        r'\(\Omega\)',
-    
-        # HTML character entities
-        'larr': r'\(\leftarrow\)', 'rarr': r'\(\rightarrow\)', 'uarr':
-        r'\(\uparrow\)', 'darr': r'\(\downarrow\)', 'harr':
-        r'\(\leftrightarrow\)', 'crarr': r'\(\hookleftarrow\)',
-        'lArr': r'\(\Leftarrow\)', 'rArr': r'\(\Rightarrow\)', 'uArr':
-        r'\(\Uparrow\)', 'dArr': r'\(\Downarrow\)', 'hArr':
-        r'\(\Leftrightarrow\)', 'copy': r'{\textcopyright}',
-        'times': r'\(\times\)', 'forall': r'\(\forall\)', 'exist':
-        r'\(\exists\)', 'part': r'\(\partial\)', 'empty':
-        r'\(\emptyset\)', 'isin': r'\(\in\)', 'notin': r'\(\notin\)',
-        'ni': r'\(\ni\)', 'prod': r'\(\prod\)', 'sum': r'\(\sum\)',
-        'prop': r'\(\propto\)', 'infin': r'\(\infty\)', 'ang':
-        r'\(\angle\)', 'and': r'\(\wedge\)', 'or': r'\(\vee\)', 'cap':
-        r'\(\cap\)', 'cup': r'\(\cup\)', 'int': r'\(\int\)', 'there4':
-        r'\(\therefore\)', 'sim': r'\(\sim\)', 'cong': r'\(\cong\)',
-        'asymp': r'\(\approx\)', 'ne': r'\(\ne\)', 'equiv':
-        r'\(\equiv\)', 'le': r'\(\le\)', 'ge': r'\(\ge\)', 'sub':
-        r'\(\subset\)', 'sup': r'\(\supset\)', 'nsub': r'\(\supset\)',
-        'sube': r'\(\subseteq\)', 'supe': r'\(\supseteq\)', 'oplus':
-        r'\(\oplus\)', 'otimes': r'\(\otimes\)', 'perp': r'\(\perp\)',
-    
-        # Alternate (long) names
-        'infinity': r'\(\infty\)', 'integral': r'\(\int\)', 'product':
-        r'\(\prod\)', '<=': r'\(\le\)', '>=': r'\(\ge\)',
-        }
-    
-    def __init__(self, dom_tree, **options):
-        self._tree = dom_tree
-        # Caching:
-        self._html = self._latex = self._plaintext = None
-        self._terms = None
-        # inline option -- mark top-level children as inline.
-        if options.get('inline') and self._tree is not None:
-            for elt in self._tree.children:
-                elt.attribs['inline'] = True
-
-    def __str__(self):
-        return str(self._tree)
-        
-    def to_html(self, docstring_linker, directory=None, docindex=None,
-                context=None, **options):
-        if self._html is not None: return self._html
-        if self._tree is None: return ''
-        indent = options.get('indent', 0)
-        self._html = self._to_html(self._tree, docstring_linker, directory, 
-                                   docindex, context, indent)
-        return self._html
-
-    def to_latex(self, docstring_linker, **options):
-        if self._latex is not None: return self._latex
-        if self._tree is None: return ''
-        indent = options.get('indent', 0)
-        self._hyperref = options.get('hyperref', 1)
-        self._latex = self._to_latex(self._tree, docstring_linker, indent)
-        return self._latex
-
-    def to_plaintext(self, docstring_linker, **options):
-        # [XX] don't cache -- different options might be used!!
-        #if self._plaintext is not None: return self._plaintext
-        if self._tree is None: return ''
-        if 'indent' in options:
-            self._plaintext = to_plaintext(self._tree,
-                                           indent=options['indent'])
-        else:
-            self._plaintext = to_plaintext(self._tree)
-        return self._plaintext
-
-    def _index_term_key(self, tree):
-        str = to_plaintext(tree)
-        str = re.sub(r'\s\s+', '-', str)
-        return "index-"+re.sub("[^a-zA-Z0-9]", "_", str)
-
-    def _to_html(self, tree, linker, directory, docindex, context,
-                 indent=0, seclevel=0):
-        if isinstance(tree, basestring):
-            return plaintext_to_html(tree)
-
-        if tree.tag == 'epytext': indent -= 2
-        if tree.tag == 'section': seclevel += 1
-
-        # Process the variables first.
-        variables = [self._to_html(c, linker, directory, docindex, context,
-                                   indent+2, seclevel)
-                    for c in tree.children]
-    
-        # Construct the HTML string for the variables.
-        childstr = ''.join(variables)
-    
-        # Perform the approriate action for the DOM tree type.
-        if tree.tag == 'para':
-            return wordwrap(
-                (tree.attribs.get('inline') and '%s' or '<p>%s</p>') % childstr,
-                indent)
-        elif tree.tag == 'code':
-            style = tree.attribs.get('style')
-            if style:
-                return '<code class="%s">%s</code>' % (style, childstr)
-            else:
-                return '<code>%s</code>' % childstr
-        elif tree.tag == 'uri':
-            return ('<a href="%s" target="_top">%s</a>' %
-                    (variables[1], variables[0]))
-        elif tree.tag == 'link':
-            return linker.translate_identifier_xref(variables[1], variables[0])
-        elif tree.tag == 'italic':
-            return '<i>%s</i>' % childstr
-        elif tree.tag == 'math':
-            return '<i class="math">%s</i>' % childstr
-        elif tree.tag == 'indexed':
-            term = Element('epytext', *tree.children, **tree.attribs)
-            return linker.translate_indexterm(ParsedEpytextDocstring(term))
-            #term_key = self._index_term_key(tree)
-            #return linker.translate_indexterm(childstr, term_key)
-        elif tree.tag == 'bold':
-            return '<b>%s</b>' % childstr
-        elif tree.tag == 'ulist':
-            return '%s<ul>\n%s%s</ul>\n' % (indent*' ', childstr, indent*' ')
-        elif tree.tag == 'olist':
-            start = tree.attribs.get('start') or ''
-            return ('%s<ol start="%s">\n%s%s</ol>\n' %
-                    (indent*' ', start, childstr, indent*' '))
-        elif tree.tag == 'li':
-            return indent*' '+'<li>\n%s%s</li>\n' % (childstr, indent*' ')
-        elif tree.tag == 'heading':
-            return ('%s<h%s class="heading">%s</h%s>\n' %
-                    ((indent-2)*' ', seclevel, childstr, seclevel))
-        elif tree.tag == 'literalblock':
-            return '<pre class="literalblock">\n%s\n</pre>\n' % childstr
-        elif tree.tag == 'doctestblock':
-            return doctest_to_html(tree.children[0].strip())
-        elif tree.tag == 'fieldlist':
-            raise AssertionError("There should not be any field lists left")
-        elif tree.tag in ('epytext', 'section', 'tag', 'arg',
-                              'name', 'target', 'html'):
-            return childstr
-        elif tree.tag == 'symbol':
-            symbol = tree.children[0]
-            return self.SYMBOL_TO_HTML.get(symbol, '[%s]' % symbol)
-        elif tree.tag == 'graph':
-            # Generate the graph.
-            graph = self._build_graph(variables[0], variables[1:], linker,
-                                      docindex, context)
-            if not graph: return ''
-            # Write the graph.
-            image_url = '%s.gif' % graph.uid
-            image_file = os.path.join(directory, image_url)
-            return graph.to_html(image_file, image_url)
-        else:
-            raise ValueError('Unknown epytext DOM element %r' % tree.tag)
-
-    #GRAPH_TYPES = ['classtree', 'packagetree', 'importgraph']
-    def _build_graph(self, graph_type, graph_args, linker, 
-                     docindex, context):
-        # Generate the graph
-        if graph_type == 'classtree':
-            from epydoc.apidoc import ClassDoc
-            if graph_args:
-                bases = [docindex.find(name, context)
-                         for name in graph_args]
-            elif isinstance(context, ClassDoc):
-                bases = [context]
-            else:
-                log.warning("Could not construct class tree: you must "
-                            "specify one or more base classes.")
-                return None
-            from epydoc.docwriter.dotgraph import class_tree_graph
-            return class_tree_graph(bases, linker, context)
-        elif graph_type == 'packagetree':
-            from epydoc.apidoc import ModuleDoc
-            if graph_args:
-                packages = [docindex.find(name, context)
-                            for name in graph_args]
-            elif isinstance(context, ModuleDoc):
-                packages = [context]
-            else:
-                log.warning("Could not construct package tree: you must "
-                            "specify one or more root packages.")
-                return None
-            from epydoc.docwriter.dotgraph import package_tree_graph
-            return package_tree_graph(packages, linker, context)
-        elif graph_type == 'importgraph':
-            from epydoc.apidoc import ModuleDoc
-            modules = [d for d in docindex.root if isinstance(d, ModuleDoc)]
-            from epydoc.docwriter.dotgraph import import_graph
-            return import_graph(modules, docindex, linker, context)
-
-        elif graph_type == 'callgraph':
-            if graph_args:
-                docs = [docindex.find(name, context) for name in graph_args]
-                docs = [doc for doc in docs if doc is not None]
-            else:
-                docs = [context]
-            from epydoc.docwriter.dotgraph import call_graph
-            return call_graph(docs, docindex, linker, context)
-        else:
-            log.warning("Unknown graph type %s" % graph_type)
-            
-    
-    def _to_latex(self, tree, linker, indent=0, seclevel=0, breakany=0):
-        if isinstance(tree, basestring):
-            return plaintext_to_latex(tree, breakany=breakany)
-
-        if tree.tag == 'section': seclevel += 1
-    
-        # Figure out the child indent level.
-        if tree.tag == 'epytext': cindent = indent
-        else: cindent = indent + 2
-        variables = [self._to_latex(c, linker, cindent, seclevel, breakany)
-                    for c in tree.children]
-        childstr = ''.join(variables)
-    
-        if tree.tag == 'para':
-            return wordwrap(childstr, indent)+'\n'
-        elif tree.tag == 'code':
-            return '\\texttt{%s}' % childstr
-        elif tree.tag == 'uri':
-            if len(variables) != 2: raise ValueError('Bad URI ')
-            if self._hyperref:
-                # ~ and # should not be escaped in the URI.
-                uri = tree.children[1].children[0]
-                uri = uri.replace('{\\textasciitilde}', '~')
-                uri = uri.replace('\\#', '#')
-                if variables[0] == variables[1]:
-                    return '\\href{%s}{\\textit{%s}}' % (uri, variables[1])
-                else:
-                    return ('%s\\footnote{\\href{%s}{%s}}' %
-                            (variables[0], uri, variables[1]))
-            else:
-                if variables[0] == variables[1]:
-                    return '\\textit{%s}' % variables[1]
-                else:
-                    return '%s\\footnote{%s}' % (variables[0], variables[1])
-        elif tree.tag == 'link':
-            if len(variables) != 2: raise ValueError('Bad Link')
-            return linker.translate_identifier_xref(variables[1], variables[0])
-        elif tree.tag == 'italic':
-            return '\\textit{%s}' % childstr
-        elif tree.tag == 'math':
-            return '\\textit{%s}' % childstr
-        elif tree.tag == 'indexed':
-            term = Element('epytext', *tree.children, **tree.attribs)
-            return linker.translate_indexterm(ParsedEpytextDocstring(term))
-        elif tree.tag == 'bold':
-            return '\\textbf{%s}' % childstr
-        elif tree.tag == 'li':
-            return indent*' ' + '\\item ' + childstr.lstrip()
-        elif tree.tag == 'heading':
-            return ' '*(indent-2) + '(section) %s\n\n' % childstr
-        elif tree.tag == 'doctestblock':
-            return doctest_to_latex(tree.children[0].strip())
-        elif tree.tag == 'literalblock':
-            return '\\begin{alltt}\n%s\\end{alltt}\n\n' % childstr
-        elif tree.tag == 'fieldlist':
-            return indent*' '+'{omitted fieldlist}\n'
-        elif tree.tag == 'olist':
-            return (' '*indent + '\\begin{enumerate}\n\n' + 
-                    ' '*indent + '\\setlength{\\parskip}{0.5ex}\n' +
-                    childstr +
-                    ' '*indent + '\\end{enumerate}\n\n')
-        elif tree.tag == 'ulist':
-            return (' '*indent + '\\begin{itemize}\n' +
-                    ' '*indent + '\\setlength{\\parskip}{0.6ex}\n' +
-                    childstr +
-                    ' '*indent + '\\end{itemize}\n\n')
-        elif tree.tag == 'symbol':
-            symbol = tree.children[0]
-            return self.SYMBOL_TO_LATEX.get(symbol, '[%s]' % symbol)
-        elif tree.tag == 'graph':
-            return '(GRAPH)'
-            #raise ValueError, 'graph not implemented yet for latex'
-        else:
-            # Assume that anything else can be passed through.
-            return childstr
-
-    _SUMMARY_RE = re.compile(r'(\s*[\w\W]*?\.)(\s|$)')
-
-    def summary(self):
-        if self._tree is None: return self, False
-        tree = self._tree
-        doc = Element('epytext')
-    
-        # Find the first paragraph.
-        variables = tree.children
-        while (len(variables) > 0) and (variables[0].tag != 'para'):
-            if variables[0].tag in ('section', 'ulist', 'olist', 'li'):
-                variables = variables[0].children
-            else:
-                variables = variables[1:]
-    
-        # Special case: if the docstring contains a single literal block,
-        # then try extracting the summary from it.
-        if (len(variables) == 0 and len(tree.children) == 1 and
-            tree.children[0].tag == 'literalblock'):
-            str = re.split(r'\n\s*(\n|$).*',
-                           tree.children[0].children[0], 1)[0]
-            variables = [Element('para')]
-            variables[0].children.append(str)
-    
-        # If we didn't find a paragraph, return an empty epytext.
-        if len(variables) == 0: return ParsedEpytextDocstring(doc), False
-    
-        # Is there anything else, excluding tags, after the first variable?
-        long_docs = False
-        for var in variables[1:]:
-            if isinstance(var, Element) and var.tag == 'fieldlist':
-                continue
-            long_docs = True
-            break
-        
-        # Extract the first sentence.
-        parachildren = variables[0].children
-        para = Element('para', inline=True)
-        doc.children.append(para)
-        for parachild in parachildren:
-            if isinstance(parachild, basestring):
-                m = self._SUMMARY_RE.match(parachild)
-                if m:
-                    para.children.append(m.group(1))
-                    long_docs |= parachild is not parachildren[-1]
-                    if not long_docs:
-                        other = parachild[m.end():]
-                        if other and not other.isspace():
-                            long_docs = True
-                    return ParsedEpytextDocstring(doc), long_docs
-            para.children.append(parachild)
-
-        return ParsedEpytextDocstring(doc), long_docs
-
-    def split_fields(self, errors=None):
-        if self._tree is None: return (self, ())
-        tree = Element(self._tree.tag, *self._tree.children,
-                       **self._tree.attribs)
-        fields = []
-
-        if (tree.children and
-            tree.children[-1].tag == 'fieldlist' and
-            tree.children[-1].children):
-            field_nodes = tree.children[-1].children
-            del tree.children[-1]
-
-            for field in field_nodes:
-                # Get the tag
-                tag = field.children[0].children[0].lower()
-                del field.children[0]
-
-                # Get the argument.
-                if field.children and field.children[0].tag == 'arg':
-                    arg = field.children[0].children[0]
-                    del field.children[0]
-                else:
-                    arg = None
-
-                # Process the field.
-                field.tag = 'epytext'
-                fields.append(Field(tag, arg, ParsedEpytextDocstring(field)))
-
-        # Save the remaining docstring as the description..
-        if tree.children and tree.children[0].children:
-            return ParsedEpytextDocstring(tree), fields
-        else:
-            return None, fields
-
-    
-    def index_terms(self):
-        if self._terms is None:
-            self._terms = []
-            self._index_terms(self._tree, self._terms)
-        return self._terms
-
-    def _index_terms(self, tree, terms):
-        if tree is None or isinstance(tree, basestring):
-            return
-        
-        if tree.tag == 'indexed':
-            term = Element('epytext', *tree.children, **tree.attribs)
-            terms.append(ParsedEpytextDocstring(term))
-
-        # Look for index items in child nodes.
-        for child in tree.children:
-            self._index_terms(child, terms)