merge from ajung-restructuredtext-integration-branch

doc/CHANGES.txt

@@ -33,6 +33,9 @@ Zope Changes
        than one attribute of an object. This removes the ties between the
        indexes ID and the attribute name to be indexed. 
 
+     - Integration of reStructuredText (reST). 
+       See doc/RESTRUCTUREDTEXT.txt for details.
+
     Bugs Fixed
 
      - Collector #771: ZCatalog failed to index DTML Document if the name

doc/RESTRUCTUREDSTEXT.txt

+Integration of reStructuredText (reST) in Zope:
+
+Zope 2.7 or higher integrates reST as part of the Python
+docutils package. The syntax of reST is defined under
+
+    http://docutils.sf.net/spec/rst/introduction.html
+
+
+Usage inside DTML:
+
+     <dtml-var rest-document fmt="restructured-text">
+
+
+Usage inside ZPT:
+
+    <span tal:content="structure python: modules['Products.PythonScripts.standard'].restructured_test(rest_txt)" />
+
+
+Usage inside PythonScripts:
+
+    from Products.PythonScripts.standard import restructured_text
+
+    rendered_html = restructured_test(rest_txt)
+    return rendered_html
+
+
+Usage inside Zope products:
+
+    from reStructuredText import HTML
+    rendered_html = HTML(rest_txt)
+    ...
+
+Character set issues:
+
+   reST processes the reST document internally using unicode. A reST
+   document is converted using Pythons default encoding to unicode and
+   converted back from unicode to the default encoding on the output side.
+   This means you must ensure that Python default encoding is properly.
+
+   You can customize the default encoding by creating a file sitecustomize.py
+   somewhere in yout PYTHONPATH:
+
+      import sys
+      sys.setdefaultencoding("iso-8859-1")
+
+
+
+This version of Zope also includes the ZReST product written by Richard Jones.
+ZRest is a standalone Zope product to handle reStructuredText documents.
+

lib/python/DocumentTemplate/DT_Var.py

@@ -151,8 +151,8 @@ Evaluating expressions without rendering results
 
 
 ''' # '
-__rcs_id__='$Id: DT_Var.py,v 1.58 2002/09/16 10:09:11 htrd Exp $'
-__version__='$Revision: 1.58 $'[11:-2]
+__rcs_id__='$Id: DT_Var.py,v 1.59 2003/02/01 09:25:58 andreasjung Exp $'
+__version__='$Revision: 1.59 $'[11:-2]
 
 from DT_Util import parse_params, name_param, str, ustr
 import os, string, re,  sys
@@ -396,6 +396,18 @@ def len_format(v, name='(Unknown name)', md={}):
 def len_comma(v, name='(Unknown name)', md={}):
     return thousands_commas(str(len(v)))
 
+def restructured_text(v, name='(Unknown name)', md={}):
+
+    from reStructuredText import HTML
+
+    if isinstance(v,StringType): txt = v
+    elif aq_base(v).meta_type in ['DTML Document','DTML Method']:
+        txt = aq_base(v).read_raw()
+    else: txt = str(v)
+
+    return HTML(txt)
+
+
 StructuredText=None
 def structured_text(v, name='(Unknown name)', md={}):
     global StructuredText
@@ -428,6 +440,7 @@ special_formats={
     'dollars-and-cents': dollars_and_cents,
     'collection-length': len_format,
     'structured-text': structured_text,
+    'restructured-text': restructured_text,
 
     # The rest are deprecated:
     'sql-quote': sql_quote,

lib/python/Products/ZReST/Makefile

+FILES = ZReST.py __init__.py refresh.txt version.txt TODO.txt README.txt
+DTML = dtml/manage_addZReSTForm.dtml dtml/manage_editForm.dtml
+VERSION := $(shell cat version.txt)
+
+all: ${FILES} ${DTML}
+	rm -rf dist
+	mkdir dist
+	mkdir dist/ZReST
+	mkdir dist/ZReST/dtml
+	cp ${FILES} dist/ZReST
+	cp ${DTML}  dist/ZReST/dtml
+	(cd dist; tar zcf ZReST-${VERSION}.tgz ZReST)
+	mv dist/ZReST-${VERSION}.tgz .
+	rm -rf dist
+

lib/python/Products/ZReST/README.txt

+----------------------------------
+ReStructuredText Document for Zope
+----------------------------------
+
+Requirements
+============
+
+To use this product, you will need:
+
+python2.1+
+   see http://www.python.org/
+Zope 2.5+
+   see http://www.zope.org/
+A docutils snapshot from later than 21 August 2002
+   see http://docutils.sourceforge.net/#development-snapshots
+
+Installation
+============
+
+To install this product, unpack it so the ZReST directory is in the Zope
+lib/python/Products directory. You should then restart Zope.
+
+You will now be able to add objects of type "ReStructuredText Document".
+
+Usage
+=====
+
+See the docutils user documentation section:
+
+   http://docutils.sourceforge.net/#user-documentation
+
+I recommend starting with the ReST "primer":
+
+   http://docutils.sourceforge.net/docs/rst/quickstart.html
+
+
+Footnotes
+=========
+
+This product was written by Richard Jones, rjones@ekit-inc.com.
+
+Please direct questions about ReStructureText to the docutils mailing lists.
+
+This package is placed in the Public Domain.
+

lib/python/Products/ZReST/TODO.txt

+. charset configuration, defaulting to 'latin-1'
+. add "level" and "header" args to render / as_html
+  - level indicates the header level to start at
+  - header boolean turns page header tags on/off
+

lib/python/Products/ZReST/ZReST.py

+# 
+# $Id: ZReST.py,v 1.2 2003/02/01 09:28:30 andreasjung Exp $
+#
+''' ReStructuredText Product for Zope
+
+This Product stores two texts - a "source" text in ReStructureText format,
+and a HTML "formatted" version of that text.
+
+'''
+import docutils.core, docutils.io
+
+from Globals import InitializeClass, DTMLFile
+from OFS.SimpleItem import Item
+from OFS.PropertyManager import PropertyManager
+from OFS.History import Historical, html_diff
+from Acquisition import Implicit
+from Persistence import Persistent
+from AccessControl import ClassSecurityInfo
+from AccessControl import ModuleSecurityInfo
+from DateTime.DateTime import DateTime
+import sys
+modulesecurity = ModuleSecurityInfo()
+
+modulesecurity.declareProtected('View management screens',
+    'manage_addZReSTForm')
+manage_addZReSTForm = DTMLFile('dtml/manage_addZReSTForm', globals())
+
+modulesecurity.declareProtected('Add Z Roundups', 'manage_addZReST')
+def manage_addZReST(self, id, file='', REQUEST=None):
+    """Add a ZReST product """
+    # validate the instance_home
+    self._setObject(id, ZReST(id))
+    self._getOb(id).manage_upload(file)
+    if REQUEST:
+        return self.manage_main(self, REQUEST)
+
+class Warnings:
+    def __init__(self):
+        self.messages = []
+    def write(self, message):
+        self.messages.append(message)
+
+class ZReST(Item, PropertyManager, Historical, Implicit, Persistent):
+    '''An instance of this class provides an interface between Zope and
+       ReStructuredText for one text.
+    '''
+    meta_type =  'ReStructuredText Document'
+    security = ClassSecurityInfo()
+
+    def __init__(self, id):
+        self.id = id
+        self.title = id
+        self.stylesheet = 'default.css'
+        self.report_level = '2'
+        self.source = self.formatted = ''
+
+    # define the properties that define this object
+    _properties = (
+        {'id':'stylesheet', 'type': 'string', 'mode': 'w',
+            'default': 'default.css'},
+        {'id':'report_level', 'type': 'string', 'mode': 'w', 'default': '2'},
+    )
+    property_extensible_schema__ = 0
+
+    # define the tabs for the management interface
+    manage_options= ( {'label': 'Edit', 'action':'manage_main'},
+                      {'label': 'View', 'action':'index_html'},
+                      {'label': 'Source', 'action':'source_txt'},
+                    ) \
+        + PropertyManager.manage_options \
+        + Historical.manage_options \
+        + Item.manage_options
+
+    # access to the source text and formatted text
+    security.declareProtected('View', 'index_html')
+    def index_html(self, REQUEST=None):
+        ''' Getting the formatted text
+        '''
+        REQUEST.RESPONSE.setHeader('content-type', 'text/html')
+        return self.formatted
+    security.declareProtected('View', 'source_txt')
+    def source_txt(self, REQUEST=None):
+        ''' Getting the source text
+        '''
+        REQUEST.RESPONSE.setHeader('content-type', 'text/plain')
+        return self.source
+
+    # edit form, which is also the primary interface
+    security.declareProtected('Edit ReStructuredText', 'manage_editForm')
+    manage_main = DTMLFile('dtml/manage_editForm', globals())
+
+    # edit action
+    security.declareProtected('Edit ReStructuredText', 'manage_edit')
+    def manage_edit(self, data, SUBMIT='Change',dtpref_cols='50',
+                    dtpref_rows='20', REQUEST=None):
+        '''Alias index_html to roundup's index
+        '''
+        if self._size_changes.has_key(SUBMIT):
+            return self._er(data, SUBMIT, dtpref_cols, dtpref_rows, REQUEST)
+        if data != self.source:
+            self.source = data
+            self.render()
+
+        if REQUEST:
+            message="Saved changes."
+            return self.manage_main(self, REQUEST, manage_tabs_message=message)
+
+    # handle edit window size changes
+    _size_changes = {
+        'Bigger': (5,5),
+        'Smaller': (-5,-5),
+        'Narrower': (0,-5),
+        'Wider': (0,5),
+        'Taller': (5,0),
+        'Shorter': (-5,0),
+    }
+    def _er(self, data, SUBMIT, dtpref_cols, dtpref_rows, REQUEST):
+        dr,dc = self._size_changes[SUBMIT]
+        rows=max(1,int(dtpref_rows)+dr)
+        cols=max(40,int(dtpref_cols)+dc)
+        e=(DateTime('GMT') + 365).rfc822()
+        resp=REQUEST['RESPONSE']
+        resp.setCookie('dtpref_rows',str(rows),path='/',expires=e)
+        resp.setCookie('dtpref_cols',str(cols),path='/',expires=e)
+        return self.manage_main(self, REQUEST, __str__=self.quotedHTML(data),
+            dtpref_cols=cols, dtpref_rows=rows)
+    security.declarePrivate('quotedHTML')
+    def quotedHTML(self,
+                   text=None,
+                   character_entities=(
+                       (('&'), '&'),
+                       (("<"), '&lt;' ),
+                       ((">"), '&gt;' ),
+                       (('"'), '&quot;'))): #"
+        if text is None: text=self.read_raw()
+        for re,name in character_entities:
+            if text.find(re) >= 0: text=name.join(text.split(re))
+        return text
+
+
+    # handle uploads too
+    security.declareProtected('Edit ReStructuredText', 'manage_upload')
+    def manage_upload(self, file='', REQUEST=None):
+        ''' Replaces the current source with the upload.
+        '''
+        if isinstance(file, type('')):
+            self.source = file
+        else:
+            self.source = file.read()
+        self.render()
+
+        if REQUEST:
+            message="Saved changes."
+            return self.manage_main(self, REQUEST, manage_tabs_message=message)
+
+    security.declarePrivate('render')
+    def render(self):
+        ''' Render the source to HTML
+        '''
+        # format with strings
+        pub = docutils.core.Publisher()
+        pub.set_reader('standalone', None, 'restructuredtext')
+        pub.set_writer('html')
+
+        # go with the defaults
+        pub.get_settings()
+
+        # this is needed, but doesn't seem to do anything
+        pub.settings._destination = ''
+
+        # use the stylesheet chosen by the user
+        pub.settings.stylesheet = self.stylesheet
+
+        # set the reporting level to something sane
+        pub.settings.report_level = int(self.report_level)
+
+        # don't break if we get errors
+        pub.settings.halt_level = 6
+
+        # remember warnings
+        pub.settings.warning_stream = Warnings()
+
+        # input
+        pub.source = docutils.io.StringInput(
+            source=self.source, encoding=sys.getdefaultencoding())
+
+        # output - not that it's needed
+        pub.destination = docutils.io.StringOutput(
+            encoding=sys.getdefaultencoding())
+
+        # parse!
+        document = pub.reader.read(pub.source, pub.parser, pub.settings)
+        self.warnings = ''.join(pub.settings.warning_stream.messages)
+
+        if document.children:
+            item = document.children[0]
+            if item.tagname == 'title':
+                self.title = str(item.children[0])
+
+        # do the format
+        self.formatted = pub.writer.write(document, pub.destination)
+
+
+    security.declareProtected('Edit ReStructuredText', 'PUT', 'manage_FTPput')
+    def PUT(self, REQUEST, RESPONSE):
+        ''' Handle HTTP PUT requests
+        '''
+        data = REQUEST.get('BODY', '')
+        if data != self.source:
+            if data.startswith('.. '):
+                data = data.splitlines()
+                new = []
+                for i in range(len(data)):
+                    line = data[i]
+                    if not line.startswith('.. '):
+                        break
+                    if line.startswith('.. stylesheet='):
+                        self.stylesheet = line.split('=')[1]
+                    elif line.startswith('.. report_level='):
+                        self.report_level = line.split('=')[1]
+                    else:
+                        pass # ignore
+                data = '\n'.join(new) + '\n'.join(data[i:])
+            self.source = data
+            self.render()
+        RESPONSE.setStatus(204)
+        return RESPONSE        
+
+    manage_FTPput = PUT
+
+    def manage_FTPget(self):
+        ''' Get source for FTP download
+        '''
+        self.REQUEST.RESPONSE.setHeader('Content-Type', 'text/plain')
+        s = [
+            '.. This is a ReStructuredText Document. Initial comment lines '
+                '(".. ") will be stripped.',
+            '.. stylesheet='+self.stylesheet,
+            '.. report_level='+self.report_level
+        ]
+        if self.warnings:
+            s.append('.. ')
+            s.append('.. ' + '\n.. '.join(self.warnings.splitlines()))
+        s.append('.. ')
+        return '\n'.join(s) + '\n' + self.source
+
+    def __str__(self):
+        ''' Stringfy .. return the source
+        '''
+        return self.quotedHTML(self.source)
+
+    def PrincipiaSearchSource(self):
+        ''' Support for searching - the document's contents are searched.
+        '''
+        return self.source
+
+    def manage_historyCompare(self, rev1, rev2, REQUEST,
+                              historyComparisonResults=''):
+        return ZReST.inheritedAttribute('manage_historyCompare')(
+            self, rev1, rev2, REQUEST,
+            historyComparisonResults=html_diff(rev1.source, rev2.source))
+
+InitializeClass(ZReST)
+modulesecurity.apply(globals())
+
+
+#
+# $Log: ZReST.py,v $
+# Revision 1.2  2003/02/01 09:28:30  andreasjung
+# merge from ajung-restructuredtext-integration-branch
+#
+# Revision 1.1.2.5  2003/01/30 19:00:24  andreasjung
+# forgot to import sys
+#
+# Revision 1.1.2.4  2003/01/30 18:10:57  andreasjung
+# using Pythons  default encoding instead of the docutils defaults
+#
+# Revision 1.1.2.3  2003/01/30 18:09:44  andreasjung
+# update from RIchards sandbox
+#
+# Revision 1.6  2002/11/28 03:44:50  goodger
+# updated
+#
+# Revision 1.5  2002/11/05 05:27:56  goodger
+# fixed Reader name
+#
+# Revision 1.4  2002/10/18 05:10:33  goodger
+# Refactored names (options -> settings; etc.); updated.
+#
+# Revision 1.3  2002/08/15 05:02:41  richard
+# pull out the document title too
+#
+# Revision 1.2  2002/08/15 04:36:56  richard
+# FTP interface and Reporter message snaffling
+#
+# Revision 1.1  2002/08/14 05:15:37  richard
+# Zope ReStructuredText Product
+#
+#
+#
+# vim: set filetype=python ts=4 sw=4 et si

lib/python/Products/ZReST/__init__.py

+# 
+# $Id: __init__.py,v 1.2 2003/02/01 09:28:30 andreasjung Exp $
+#
+__version__='1.0'
+
+# product initialisation
+import ZReST
+def initialize(context):
+    context.registerClass(
+        ZReST, meta_type = 'ReStructuredText Document',
+        constructors = (
+            ZReST.manage_addZReSTForm, ZReST.manage_addZReST
+        )
+    )
+
+
+#
+# $Log: __init__.py,v $
+# Revision 1.2  2003/02/01 09:28:30  andreasjung
+# merge from ajung-restructuredtext-integration-branch
+#
+# Revision 1.1.2.2  2002/11/06 16:09:36  andreasjung
+# updated to ZReST 1.1
+#
+# Revision 1.2  2002/08/15 04:36:56  richard
+# FTP interface and Reporter message snaffling
+#
+# Revision 1.1  2002/08/14 05:15:37  richard
+# Zope ReStructuredText Product
+#
+#
+#
+# vim: set filetype=python ts=4 sw=4 et si

lib/python/Products/ZReST/dtml/manage_addZReSTForm.dtml

+<dtml-var manage_page_header>
+
+<dtml-var "manage_form_title(this(), _, form_title='Add ReStructureText Document')">
+
+<p class="form-help">
+You may optionally select a file to upload from your local computer by
+clicking the <em>Browse</em> button.
+</p>
+
+<form action="manage_addZReST" method="post" enctype="multipart/form-data">
+<table cellspacing="0" cellpadding="2" border="0">
+  <tr>
+    <td align="left" valign="top">
+    <div class="form-label">
+    Id
+    </div>
+    </td>
+    <td align="left" valign="top">
+    <input type="text" name="id" size="40" />
+    </td>
+  </tr>
+  <tr>
+    <td align="left" valign="top">
+    <div class="form-optional">
+    File
+    </div>
+    </td>
+    <td align="left" valign="top">
+    <input type="file" name="file" size="25" value="" />
+    </td>
+  </tr>
+  <tr>
+    <td align="left" valign="top">
+    </td>
+    <td align="left" valign="top">
+    <div class="form-element">
+    <input class="form-element" type="submit" name="submit" 
+     value=" Add " /> 
+    </div>
+    </td>
+  </tr>
+</table>
+</form>
+
+<dtml-var manage_page_footer>

lib/python/Products/ZReST/dtml/manage_editForm.dtml

+<dtml-var manage_page_header>
+<dtml-var manage_tabs>
+
+<p class="form-help">
+You may edit the source for this document using the form below. You 
+may also upload the source for this document from a local file. Click
+the <em>browse</em> button to select a local file to upload.
+</p>
+
+<dtml-if warnings>
+<pre class="system-msg">
+&dtml-warnings;
+</pre>
+</dtml-if>
+
+<p class="form-help"><strong>Help:</strong> ReStructuredText
+ <a href="http://docutils.sourceforge.net/docs/rst/quickstart.html">primer</a>
+  for beginners,
+ <a href="http://docutils.sourceforge.net/docs/rst/quickref.html">quick
+  reference</a> for the more advanced and
+ <a href="http://docutils.sourceforge.net/rst.html">home page</a> for all
+  the details.
+</p>
+
+<form action="manage_edit" method="post">
+<table cellpadding="2" cellspacing="0" width="100%" border="0">
+
+<dtml-with keyword_args mapping>
+<tr>
+  <td align="left" valign="top" colspan="2">
+  <div style="width: 100%;">
+  <textarea name="data:text" wrap="off" style="width: 100%;"<dtml-if 
+   dtpref_cols> cols="<dtml-var dtpref_cols>"<dtml-else
+   > cols="50"</dtml-if><dtml-if dtpref_rows> rows="<dtml-var 
+   dtpref_rows>"<dtml-else> rows="20"</dtml-if>><dtml-var 
+   __str__></textarea>
+  </div>
+  </td>
+</tr>
+</dtml-with>
+
+<tr>
+  <td align="left" valign="top" colspan="2">
+  <div class="form-element">
+  <dtml-if wl_isLocked>
+   <em>Locked by WebDAV</em>
+  <dtml-else>
+   <input class="form-element" type="submit" name="SUBMIT" value="Save Changes">
+  </dtml-if>
+  &nbsp;&nbsp;
+  <input class="form-element" type="submit" name="SUBMIT" value="Taller">
+  <input class="form-element" type="submit" name="SUBMIT" value="Shorter">
+  <input class="form-element" type="submit" name="SUBMIT" value="Wider">
+  <input class="form-element" type="submit" name="SUBMIT" value="Narrower">
+  </div>
+  </td>
+</tr>
+</table>
+</form>
+
+<form action="manage_upload" method="post" enctype="multipart/form-data">
+<table cellpadding="2" cellspacing="0" border="0">
+<tr>
+  <td align="left" valign="top">
+  <div class="form-label">
+  File &nbsp;
+  </div>
+  </td>
+  <td align="left" valign="top">
+  <input type="file" name="file" size="25" value="">
+  </td>
+</tr>
+<tr>
+  <td></td>
+  <td align="left" valign="top">
+  <div class="form-element">
+  <dtml-if wl_isLocked>
+   <em>Locked by WebDAV</em>
+  <dtml-else>
+   <input class="form-element" type="submit" value="Upload File">
+  </dtml-if>
+  </div>
+  </td>
+</tr>
+</table>
+</form>
+
+<dtml-var manage_page_footer>

lib/python/Products/ZReST/refresh.txt

+This is a flag that tells Zope that the product may be auto-refreshed.

lib/python/Products/ZReST/version.txt

+1.1

lib/python/docutils/__init__.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:00 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+This is the Docutils (Python Documentation Utilities) package.
+
+Package Structure
+=================
+
+Modules:
+
+- __init__.py: Contains the package docstring only (this text).
+
+- core.py: Contains the ``Publisher`` class and ``publish()`` convenience
+  function.
+
+- frontend.py: Command-line and common processing for Docutils front-ends.
+
+- io.py: Provides a uniform API for low-level input and output.
+
+- nodes.py: Docutils document tree (doctree) node class library.
+
+- optik.py: Option parsing and command-line help; from Greg Ward's
+  http://optik.sf.net/ project, included for convenience.
+
+- roman.py: Conversion to and from Roman numerals. Courtesy of Mark
+  Pilgrim (http://diveintopython.org/).
+
+- statemachine.py: A finite state machine specialized for
+  regular-expression-based text filters.
+
+- urischemes.py: Contains a complete mapping of known URI addressing
+  scheme names to descriptions.
+
+- utils.py: Contains the ``Reporter`` system warning class and miscellaneous
+  utilities.
+
+Subpackages:
+
+- languages: Language-specific mappings of terms.
+
+- parsers: Syntax-specific input parser modules or packages.
+
+- readers: Context-specific input handlers which understand the data
+  source and manage a parser.
+
+- transforms: Modules used by readers and writers to modify DPS
+  doctrees.
+
+- writers: Format-specific output translators.
+"""
+
+__docformat__ = 'reStructuredText'
+
+__version__ = '0.2.8'
+"""``major.minor.micro`` version number.  The micro number is bumped any time
+there's a change in the API incompatible with one of the front ends.  The
+minor number is bumped whenever there is a project release.  The major number
+will be bumped when the project is complete, and perhaps if there is a major
+change in the design."""
+
+
+class ApplicationError(StandardError): pass
+class DataError(ApplicationError): pass
+
+
+class SettingsSpec:
+
+    """
+    Runtime setting specification base class.
+
+    SettingsSpec subclass objects used by `docutils.frontend.OptionParser`.
+    """
+
+    settings_spec = ()
+    """Runtime settings specification.  Override in subclasses.
+
+    Specifies runtime settings and associated command-line options, as used by
+    `docutils.frontend.OptionParser`.  This tuple contains one or more sets of
+    option group title, description, and a list/tuple of tuples: ``('help
+    text', [list of option strings], {keyword arguments})``.  Group title
+    and/or description may be `None`; no group title implies no group, just a
+    list of single options.  Runtime settings names are derived implicitly
+    from long option names ("--a-setting" becomes ``settings.a_setting``) or
+    explicitly from the "destination" keyword argument."""
+
+    settings_default_overrides = None
+    """A dictionary of auxiliary defaults, to override defaults for settings
+    defined in other components.  Override in subclasses."""
+
+    relative_path_settings = ()
+    """Settings containing filesystem paths.  Override in subclasses.
+
+    Settings listed here are to be interpreted relative to the current working
+    directory."""
+
+
+class TransformSpec:
+
+    """
+    Runtime transform specification base class.
+
+    TransformSpec subclass objects used by `docutils.transforms.Transformer`.
+    """
+
+    default_transforms = ()
+    """Transforms required by this class.  Override in subclasses."""
+
+
+class Component(SettingsSpec, TransformSpec):
+
+    """Base class for Docutils components."""
+
+    component_type = None
+    """Override in subclasses."""
+
+    supported = ()
+    """Names for this component.  Override in subclasses."""
+
+    def supports(self, format):
+        """
+        Is `format` supported by this component?
+
+        To be used by transforms to ask the dependent component if it supports
+        a certain input context or output format.
+        """
+        return format in self.supported

lib/python/docutils/core.py

+# Authors: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:00 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Calling the ``publish_*`` convenience functions (or instantiating a
+`Publisher` object) with component names will result in default
+behavior.  For custom behavior (setting component options), create
+custom component objects first, and pass *them* to
+``publish_*``/`Publisher`.
+"""
+
+__docformat__ = 'reStructuredText'
+
+import sys
+from docutils import Component
+from docutils import frontend, io, readers, parsers, writers
+from docutils.frontend import OptionParser, ConfigParser
+
+
+class Publisher:
+
+    """
+    A facade encapsulating the high-level logic of a Docutils system.
+    """
+
+    def __init__(self, reader=None, parser=None, writer=None,
+                 source=None, source_class=io.FileInput,
+                 destination=None, destination_class=io.FileOutput,
+                 settings=None):
+        """
+        Initial setup.  If any of `reader`, `parser`, or `writer` are not
+        specified, the corresponding ``set_...`` method should be called with
+        a component name (`set_reader` sets the parser as well).
+        """
+
+        self.reader = reader
+        """A `readers.Reader` instance."""
+
+        self.parser = parser
+        """A `parsers.Parser` instance."""
+
+        self.writer = writer
+        """A `writers.Writer` instance."""
+
+        self.source = source
+        """The source of input data, an `io.Input` instance."""
+
+        self.source_class = source_class
+        """The class for dynamically created source objects."""
+
+        self.destination = destination
+        """The destination for docutils output, an `io.Output` instance."""
+
+        self.destination_class = destination_class
+        """The class for dynamically created destination objects."""
+
+        self.settings = settings
+        """An object containing Docutils settings as instance attributes.
+        Set by `self.process_command_line()` or `self.get_settings()`."""
+
+    def set_reader(self, reader_name, parser, parser_name):
+        """Set `self.reader` by name."""
+        reader_class = readers.get_reader_class(reader_name)
+        self.reader = reader_class(parser, parser_name)
+        self.parser = self.reader.parser
+
+    def set_writer(self, writer_name):
+        """Set `self.writer` by name."""
+        writer_class = writers.get_writer_class(writer_name)
+        self.writer = writer_class()
+
+    def set_components(self, reader_name, parser_name, writer_name):
+        if self.reader is None:
+            self.set_reader(reader_name, self.parser, parser_name)
+        if self.parser is None:
+            if self.reader.parser is None:
+                self.reader.set_parser(parser_name)
+            self.parser = self.reader.parser
+        if self.writer is None:
+            self.set_writer(writer_name)
+
+    def setup_option_parser(self, usage=None, description=None,
+                            settings_spec=None, **defaults):
+        #@@@ Add self.source & self.destination to components in future?
+        option_parser = OptionParser(
+            components=(settings_spec, self.parser, self.reader, self.writer),
+            usage=usage, description=description)
+        config = ConfigParser()
+        config.read_standard_files()
+        config_settings = config.get_section('options')
+        frontend.make_paths_absolute(config_settings,
+                                     option_parser.relative_path_settings)
+        defaults.update(config_settings)
+        option_parser.set_defaults(**defaults)
+        return option_parser
+
+    def get_settings(self, usage=None, description=None,
+                     settings_spec=None, **defaults):
+        """
+        Set and return default settings (overrides in `defaults` keyword
+        argument).
+
+        Set components first (`self.set_reader` & `self.set_writer`).
+        Explicitly setting `self.settings` disables command line option
+        processing from `self.publish()`.
+        """
+        option_parser = self.setup_option_parser(usage, description,
+                                                 settings_spec, **defaults)
+        self.settings = option_parser.get_default_values()
+        return self.settings
+
+    def process_command_line(self, argv=None, usage=None, description=None,
+                             settings_spec=None, **defaults):
+        """
+        Pass an empty list to `argv` to avoid reading `sys.argv` (the
+        default).
+
+        Set components first (`self.set_reader` & `self.set_writer`).
+        """
+        option_parser = self.setup_option_parser(usage, description,
+                                                 settings_spec, **defaults)
+        if argv is None:
+            argv = sys.argv[1:]
+        self.settings = option_parser.parse_args(argv)
+
+    def set_io(self, source_path=None, destination_path=None):
+        if self.source is None:
+            self.set_source(source_path=source_path)
+        if self.destination is None:
+            self.set_destination(destination_path=destination_path)
+
+    def set_source(self, source=None, source_path=None):
+        if source_path is None:
+            source_path = self.settings._source
+        else:
+            self.settings._source = source_path
+        self.source = self.source_class(
+            source=source, source_path=source_path,
+            encoding=self.settings.input_encoding)
+
+    def set_destination(self, destination=None, destination_path=None):
+        if destination_path is None:
+            destination_path = self.settings._destination
+        else:
+            self.settings._destination = destination_path
+        self.destination = self.destination_class(
+            destination=destination, destination_path=destination_path,
+            encoding=self.settings.output_encoding)
+
+    def apply_transforms(self, document):
+        document.transformer.populate_from_components(
+            (self.source, self.reader, self.reader.parser, self.writer,
+             self.destination))
+        document.transformer.apply_transforms()
+
+    def publish(self, argv=None, usage=None, description=None,
+                settings_spec=None, settings_overrides=None):
+        """
+        Process command line options and arguments (if `self.settings` not
+        already set), run `self.reader` and then `self.writer`.  Return
+        `self.writer`'s output.
+        """
+        if self.settings is None:
+            self.process_command_line(argv, usage, description, settings_spec,
+                                      **(settings_overrides or {}))
+        elif settings_overrides:
+            self.settings._update(settings_overrides, 'loose')
+        self.set_io()
+        document = self.reader.read(self.source, self.parser, self.settings)
+        self.apply_transforms(document)
+        output = self.writer.write(document, self.destination)
+        if self.settings.dump_settings:
+            from pprint import pformat
+            print >>sys.stderr, '\n::: Runtime settings:'
+            print >>sys.stderr, pformat(self.settings.__dict__)
+        if self.settings.dump_internals:
+            from pprint import pformat
+            print >>sys.stderr, '\n::: Document internals:'
+            print >>sys.stderr, pformat(document.__dict__)
+        if self.settings.dump_transforms:
+            from pprint import pformat
+            print >>sys.stderr, '\n::: Transforms applied:'
+            print >>sys.stderr, pformat(document.transformer.applied)
+        if self.settings.dump_pseudo_xml:
+            print >>sys.stderr, '\n::: Pseudo-XML:'
+            print >>sys.stderr, document.pformat().encode(
+                'raw_unicode_escape')
+        return output
+
+
+default_usage = '%prog [options] [<source> [<destination>]]'
+default_description = ('Reads from <source> (default is stdin) and writes to '
+                       '<destination> (default is stdout).')
+
+def publish_cmdline(reader=None, reader_name='standalone',
+                    parser=None, parser_name='restructuredtext',
+                    writer=None, writer_name='pseudoxml',
+                    settings=None, settings_spec=None,
+                    settings_overrides=None, argv=None,
+                    usage=default_usage, description=default_description):
+    """
+    Set up & run a `Publisher`.  For command-line front ends.
+
+    Parameters:
+
+    - `reader`: A `docutils.readers.Reader` object.
+    - `reader_name`: Name or alias of the Reader class to be instantiated if
+      no `reader` supplied.
+    - `parser`: A `docutils.parsers.Parser` object.
+    - `parser_name`: Name or alias of the Parser class to be instantiated if
+      no `parser` supplied.
+    - `writer`: A `docutils.writers.Writer` object.
+    - `writer_name`: Name or alias of the Writer class to be instantiated if
+      no `writer` supplied.
+    - `settings`: Runtime settings object.
+    - `settings_spec`: Extra settings specification; a `docutils.SettingsSpec`
+      subclass.  Used only if no `settings` specified.
+    - `settings_overrides`: A dictionary containing program-specific overrides
+      of component settings.
+    - `argv`: Command-line argument list to use instead of ``sys.argv[1:]``.
+    - `usage`: Usage string, output if there's a problem parsing the command
+      line.
+    - `description`: Program description, output for the "--help" option
+      (along with command-line option descriptions).
+    """
+    pub = Publisher(reader, parser, writer, settings=settings)
+    pub.set_components(reader_name, parser_name, writer_name)
+    pub.publish(argv, usage, description, settings_spec, settings_overrides)
+
+def publish_file(source=None, source_path=None,
+                 destination=None, destination_path=None,
+                 reader=None, reader_name='standalone',
+                 parser=None, parser_name='restructuredtext',
+                 writer=None, writer_name='pseudoxml',
+                 settings=None, settings_spec=None, settings_overrides=None):
+    """
+    Set up & run a `Publisher`.  For programmatic use with file-like I/O.
+
+    Parameters:
+
+    - `source`: A file-like object (must have "read" and "close" methods).
+    - `source_path`: Path to the input file.  Opened if no `source` supplied.
+      If neither `source` nor `source_path` are supplied, `sys.stdin` is used.
+    - `destination`: A file-like object (must have "write" and "close"
+      methods).
+    - `destination_path`: Path to the input file.  Opened if no `destination`
+      supplied.  If neither `destination` nor `destination_path` are supplied,
+      `sys.stdout` is used.
+    - `reader`: A `docutils.readers.Reader` object.
+    - `reader_name`: Name or alias of the Reader class to be instantiated if
+      no `reader` supplied.
+    - `parser`: A `docutils.parsers.Parser` object.
+    - `parser_name`: Name or alias of the Parser class to be instantiated if
+      no `parser` supplied.
+    - `writer`: A `docutils.writers.Writer` object.
+    - `writer_name`: Name or alias of the Writer class to be instantiated if
+      no `writer` supplied.
+    - `settings`: Runtime settings object.
+    - `settings_spec`: Extra settings specification; a `docutils.SettingsSpec`
+      subclass.  Used only if no `settings` specified.
+    - `settings_overrides`: A dictionary containing program-specific overrides
+      of component settings.
+    """
+    pub = Publisher(reader, parser, writer, settings=settings)
+    pub.set_components(reader_name, parser_name, writer_name)
+    if settings is None:
+        settings = pub.get_settings(settings_spec=settings_spec)
+    if settings_overrides:
+        settings._update(settings_overrides, 'loose')
+    pub.set_source(source, source_path)
+    pub.set_destination(destination, destination_path)
+    pub.publish()
+
+def publish_string(source, source_path=None, destination_path=None, 
+                   reader=None, reader_name='standalone',
+                   parser=None, parser_name='restructuredtext',
+                   writer=None, writer_name='pseudoxml',
+                   settings=None, settings_spec=None,
+                   settings_overrides=None):
+    """
+    Set up & run a `Publisher`, and return the string output.
+    For programmatic use with string I/O.
+
+    For encoded string output, be sure to set the "output_encoding" setting to
+    the desired encoding.  Set it to "unicode" for unencoded Unicode string
+    output.
+
+    Parameters:
+
+    - `source`: An input string; required.  This can be an encoded 8-bit
+      string (set the "input_encoding" setting to the correct encoding) or a
+      Unicode string (set the "input_encoding" setting to "unicode").
+    - `source_path`: Path to the file or object that produced `source`;
+      optional.  Only used for diagnostic output.
+    - `destination_path`: Path to the file or object which will receive the
+      output; optional.  Used for determining relative paths (stylesheets,
+      source links, etc.).
+    - `reader`: A `docutils.readers.Reader` object.
+    - `reader_name`: Name or alias of the Reader class to be instantiated if
+      no `reader` supplied.
+    - `parser`: A `docutils.parsers.Parser` object.
+    - `parser_name`: Name or alias of the Parser class to be instantiated if
+      no `parser` supplied.
+    - `writer`: A `docutils.writers.Writer` object.
+    - `writer_name`: Name or alias of the Writer class to be instantiated if
+      no `writer` supplied.
+    - `settings`: Runtime settings object.
+    - `settings_spec`: Extra settings specification; a `docutils.SettingsSpec`
+      subclass.  Used only if no `settings` specified.
+    - `settings_overrides`: A dictionary containing program-specific overrides
+      of component settings.
+    """
+    pub = Publisher(reader, parser, writer, settings=settings,
+                    source_class=io.StringInput,
+                    destination_class=io.StringOutput)
+    pub.set_components(reader_name, parser_name, writer_name)
+    if settings is None:
+        settings = pub.get_settings(settings_spec=settings_spec)
+    if settings_overrides:
+        settings._update(settings_overrides, 'loose')
+    pub.set_source(source, source_path)
+    pub.set_destination(destination_path=destination_path)
+    return pub.publish()

lib/python/docutils/frontend.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:00 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Command-line and common processing for Docutils front-end tools.
+
+Exports the following classes:
+
+- `OptionParser`: Standard Docutils command-line processing.
+- `Values`: Runtime settings; objects are simple structs
+  (``object.attribute``).
+- `ConfigParser`: Standard Docutils config file processing.
+"""
+
+__docformat__ = 'reStructuredText'
+
+import os
+import os.path
+import ConfigParser as CP
+import docutils
+from docutils import optik
+from docutils.optik import Values
+
+
+def store_multiple(option, opt, value, parser, *args, **kwargs):
+    """
+    Store multiple values in `parser.values`.  (Option callback.)
+    
+    Store `None` for each attribute named in `args`, and store the value for
+    each key (attribute name) in `kwargs`.
+    """
+    for attribute in args:
+        setattr(parser.values, attribute, None)
+    for key, value in kwargs.items():
+        setattr(parser.values, key, value)
+
+def read_config_file(option, opt, value, parser):
+    """
+    Read a configuration file during option processing.  (Option callback.)
+    """
+    config_parser = ConfigParser()
+    config_parser.read(value)
+    settings = config_parser.get_section('options')
+    make_paths_absolute(settings, parser.relative_path_settings,
+                        os.path.dirname(value))
+    parser.values.__dict__.update(settings)
+
+def make_paths_absolute(pathdict, keys, base_path=None):
+    """
+    Interpret filesystem path settings relative to the `base_path` given.
+
+    Paths are values in `pathdict` whose keys are in `keys`.  Get `keys` from
+    `OptionParser.relative_path_settings`.
+    """
+    if base_path is None:
+        base_path = os.getcwd()
+    for key in keys:
+        if pathdict.has_key(key) and pathdict[key]:
+            pathdict[key] = os.path.normpath(
+                os.path.abspath(os.path.join(base_path, pathdict[key])))
+
+
+class OptionParser(optik.OptionParser, docutils.SettingsSpec):
+
+    """
+    Parser for command-line and library use.  The `settings_spec`
+    specification here and in other Docutils components are merged to build
+    the set of command-line options and runtime settings for this process.
+
+    Common settings (defined below) and component-specific settings must not
+    conflict.  Short options are reserved for common settings, and components
+    are restrict to using long options.
+    """
+
+    threshold_choices = 'info 1 warning 2 error 3 severe 4 none 5'.split()
+    """Possible inputs for for --report and --halt threshold values."""
+
+    thresholds = {'info': 1, 'warning': 2, 'error': 3, 'severe': 4, 'none': 5}
+    """Lookup table for --report and --halt threshold values."""
+
+    settings_spec = (
+        'General Docutils Options',
+        None,
+        (('Include a "Generated by Docutils" credit and link at the end '
+          'of the document.',
+          ['--generator', '-g'], {'action': 'store_true'}),
+         ('Do not include a generator credit.',
+          ['--no-generator'], {'action': 'store_false', 'dest': 'generator'}),
+         ('Include the date at the end of the document (UTC).',
+          ['--date', '-d'], {'action': 'store_const', 'const': '%Y-%m-%d',
+                             'dest': 'datestamp'}),
+         ('Include the time & date at the end of the document (UTC).',
+          ['--time', '-t'], {'action': 'store_const',
+                             'const': '%Y-%m-%d %H:%M UTC',
+                             'dest': 'datestamp'}),
+         ('Do not include a datestamp of any kind.',
+          ['--no-datestamp'], {'action': 'store_const', 'const': None,
+                               'dest': 'datestamp'}),
+         ('Include a "View document source" link (relative to destination).',
+          ['--source-link', '-s'], {'action': 'store_true'}),
+         ('Use the supplied <URL> verbatim for a "View document source" '
+          'link; implies --source-link.',
+          ['--source-url'], {'metavar': '<URL>'}),
+         ('Do not include a "View document source" link.',
+          ['--no-source-link'],
+          {'action': 'callback', 'callback': store_multiple,
+           'callback_args': ('source_link', 'source_url')}),
+         ('Enable backlinks from section headers to table of contents '
+          'entries.  This is the default.',
+          ['--toc-entry-backlinks'],
+          {'dest': 'toc_backlinks', 'action': 'store_const', 'const': 'entry',
+           'default': 'entry'}),
+         ('Enable backlinks from section headers to the top of the table of '
+          'contents.',
+          ['--toc-top-backlinks'],
+          {'dest': 'toc_backlinks', 'action': 'store_const', 'const': 'top'}),
+         ('Disable backlinks to the table of contents.',
+          ['--no-toc-backlinks'],
+          {'dest': 'toc_backlinks', 'action': 'store_false'}),
+         ('Enable backlinks from footnotes and citations to their '
+          'references.  This is the default.',
+          ['--footnote-backlinks'],
+          {'action': 'store_true', 'default': 1}),
+         ('Disable backlinks from footnotes and citations.',
+          ['--no-footnote-backlinks'],
+          {'dest': 'footnote_backlinks', 'action': 'store_false'}),
+         ('Set verbosity threshold; report system messages at or higher than '
+          '<level> (by name or number: "info" or "1", warning/2, error/3, '
+          'severe/4; also, "none" or "5").  Default is 2 (warning).',
+          ['--report', '-r'], {'choices': threshold_choices, 'default': 2,
+                               'dest': 'report_level', 'metavar': '<level>'}),
+         ('Report all system messages, info-level and higher.  (Same as '
+          '"--report=info".)',
+          ['--verbose', '-v'], {'action': 'store_const', 'const': 'info',
+                                'dest': 'report_level'}),
+         ('Do not report any system messages.  (Same as "--report=none".)',
+          ['--quiet', '-q'], {'action': 'store_const', 'const': 'none',
+                              'dest': 'report_level'}),
+         ('Set the threshold (<level>) at or above which system messages are '
+          'converted to exceptions, halting execution immediately.  Levels '
+          'as in --report.  Default is 4 (severe).',
+          ['--halt'], {'choices': threshold_choices, 'dest': 'halt_level',
+                       'default': 4, 'metavar': '<level>'}),
+         ('Same as "--halt=info": halt processing at the slightest problem.',
+          ['--strict'], {'action': 'store_const', 'const': 'info',
+                         'dest': 'halt_level'}),
+         ('Report debug-level system messages.',
+          ['--debug'], {'action': 'store_true'}),
+         ('Do not report debug-level system messages.',
+          ['--no-debug'], {'action': 'store_false', 'dest': 'debug'}),
+         ('Send the output of system messages (warnings) to <file>.',
+          ['--warnings'], {'dest': 'warning_stream', 'metavar': '<file>'}),
+         ('Specify the encoding of input text.  Default is locale-dependent.',
+          ['--input-encoding', '-i'], {'metavar': '<name>'}),
+         ('Specify the encoding for output.  Default is UTF-8.',
+          ['--output-encoding', '-o'],
+          {'metavar': '<name>', 'default': 'utf-8'}),
+         ('Specify the language of input text (ISO 639 2-letter identifier).'
+          '  Default is "en" (English).',
+          ['--language', '-l'], {'dest': 'language_code', 'default': 'en',
+                                 'metavar': '<name>'}),
+         ('Read configuration settings from <file>, if it exists.',
+          ['--config'], {'metavar': '<file>', 'type': 'string',
+                         'action': 'callback', 'callback': read_config_file}),
+         ("Show this program's version number and exit.",
+          ['--version', '-V'], {'action': 'version'}),
+         ('Show this help message and exit.',
+          ['--help', '-h'], {'action': 'help'}),
+         # Hidden options, for development use only:
+         (optik.SUPPRESS_HELP,
+          ['--dump-settings'],
+          {'action': 'store_true'}),
+         (optik.SUPPRESS_HELP,
+          ['--dump-internals'],
+          {'action': 'store_true'}),
+         (optik.SUPPRESS_HELP,
+          ['--dump-transforms'],
+          {'action': 'store_true'}),
+         (optik.SUPPRESS_HELP,
+          ['--dump-pseudo-xml'],
+          {'action': 'store_true'}),
+         (optik.SUPPRESS_HELP,
+          ['--expose-internal-attribute'],
+          {'action': 'append', 'dest': 'expose_internals'}),))
+    """Runtime settings and command-line options common to all Docutils front
+    ends.  Setting specs specific to individual Docutils components are also
+    used (see `populate_from_components()`)."""
+
+    relative_path_settings = ('warning_stream',)
+
+    version_template = '%%prog (Docutils %s)' % docutils.__version__
+    """Default version message."""
+
+    def __init__(self, components=(), *args, **kwargs):
+        """
+        `components` is a list of Docutils components each containing a
+        ``.settings_spec`` attribute.  `defaults` is a mapping of setting
+        default overrides.
+        """
+        optik.OptionParser.__init__(
+            self, help=None,
+            format=optik.Titled(),
+            # Needed when Optik is updated (replaces above 2 lines):
+            #self, add_help=None,
+            #formatter=optik.TitledHelpFormatter(width=78),
+            *args, **kwargs)
+        if not self.version:
+            self.version = self.version_template
+        # Internal settings with no defaults from settings specifications;
+        # initialize manually:
+        self.set_defaults(_source=None, _destination=None)
+        # Make an instance copy (it will be modified):
+        self.relative_path_settings = list(self.relative_path_settings)
+        self.populate_from_components(tuple(components) + (self,))
+
+    def populate_from_components(self, components):
+        for component in components:
+            if component is None:
+                continue
+            i = 0
+            settings_spec = component.settings_spec
+            self.relative_path_settings.extend(
+                component.relative_path_settings)
+            while i < len(settings_spec):
+                title, description, option_spec = settings_spec[i:i+3]
+                if title:
+                    group = optik.OptionGroup(self, title, description)
+                    self.add_option_group(group)
+                else:
+                    group = self        # single options
+                for (help_text, option_strings, kwargs) in option_spec:
+                    group.add_option(help=help_text, *option_strings,
+                                     **kwargs)
+                i += 3
+        for component in components:
+            if component and component.settings_default_overrides:
+                self.defaults.update(component.settings_default_overrides)
+
+    def check_values(self, values, args):
+        if hasattr(values, 'report_level'):
+            values.report_level = self.check_threshold(values.report_level)
+        if hasattr(values, 'halt_level'):
+            values.halt_level = self.check_threshold(values.halt_level)
+        values._source, values._destination = self.check_args(args)
+        make_paths_absolute(values.__dict__, self.relative_path_settings,
+                            os.getcwd())
+        return values
+
+    def check_threshold(self, level):
+        try:
+            return int(level)
+        except ValueError:
+            try:
+                return self.thresholds[level.lower()]
+            except (KeyError, AttributeError):
+                self.error('Unknown threshold: %r.' % level)
+
+    def check_args(self, args):
+        source = destination = None
+        if args:
+            source = args.pop(0)
+        if args:
+            destination = args.pop(0)
+        if args:
+            self.error('Maximum 2 arguments allowed.')
+        if source and source == destination:
+            self.error('Do not specify the same file for both source and '
+                       'destination.  It will clobber the source file.')
+        return source, destination
+
+
+class ConfigParser(CP.ConfigParser):
+
+    standard_config_files = (
+        '/etc/docutils.conf',               # system-wide
+        './docutils.conf',                  # project-specific
+        os.path.expanduser('~/.docutils'))  # user-specific
+    """Docutils configuration files, using ConfigParser syntax (section
+    'options').  Later files override earlier ones."""
+
+    def read_standard_files(self):
+        self.read(self.standard_config_files)
+
+    def optionxform(self, optionstr):
+        """
+        Transform '-' to '_' so the cmdline form of option names can be used.
+        """
+        return optionstr.lower().replace('-', '_')
+
+    def get_section(self, section, raw=0, vars=None):
+        """
+        Return a given section as a dictionary (empty if the section
+        doesn't exist).
+
+        All % interpolations are expanded in the return values, based on the
+        defaults passed into the constructor, unless the optional argument
+        `raw` is true.  Additional substitutions may be provided using the
+        `vars` argument, which must be a dictionary whose contents overrides
+        any pre-existing defaults.
+
+        The section DEFAULT is special.
+        """
+        section_dict = {}
+        if self.has_section(section):
+            for option in self.options(section):
+                section_dict[option] = self.get(section, option, raw, vars)
+        return section_dict

lib/python/docutils/io.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:00 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+I/O classes provide a uniform API for low-level input and output.  Subclasses
+will exist for a variety of input/output mechanisms.
+"""
+
+__docformat__ = 'reStructuredText'
+
+import sys
+import locale
+from docutils import TransformSpec
+
+
+class Input(TransformSpec):
+
+    """
+    Abstract base class for input wrappers.
+    """
+
+    component_type = 'input'
+
+    default_source_path = None
+
+    def __init__(self, settings=None, source=None, source_path=None,
+                 encoding=None):
+        self.encoding = encoding
+        """The character encoding for the input source."""
+
+        if settings:
+            if not encoding:
+                self.encoding = settings.input_encoding
+            import warnings, traceback
+            warnings.warn(
+                'Setting input encoding via a "settings" struct is '
+                'deprecated; send encoding directly instead.\n%s'
+                % ''.join(traceback.format_list(traceback.extract_stack()
+                                                [-3:-1])))
+
+        self.source = source
+        """The source of input data."""
+
+        self.source_path = source_path
+        """A text reference to the source."""
+
+        if not source_path:
+            self.source_path = self.default_source_path
+
+    def __repr__(self):
+        return '%s: source=%r, source_path=%r' % (self.__class__, self.source,
+                                                  self.source_path)
+
+    def read(self):
+        raise NotImplementedError
+
+    def decode(self, data):
+        """
+        Decode a string, `data`, heuristically.
+        Raise UnicodeError if unsuccessful.
+
+        The client application should call ``locale.setlocale`` at the
+        beginning of processing::
+
+            locale.setlocale(locale.LC_ALL, '')
+        """
+        if self.encoding and self.encoding.lower() == 'unicode':
+            return unicode(data)
+        encodings = [self.encoding, 'utf-8']
+        try:
+            encodings.append(locale.nl_langinfo(locale.CODESET))
+        except:
+            pass
+        try:
+            encodings.append(locale.getlocale()[1])
+        except:
+            pass
+        try:
+            encodings.append(locale.getdefaultlocale()[1])
+        except:
+            pass
+        encodings.append('latin-1')
+        for enc in encodings:
+            if not enc:
+                continue
+            try:
+                decoded = unicode(data, enc)
+                return decoded
+            except (UnicodeError, LookupError):
+                pass
+        raise UnicodeError(
+            'Unable to decode input data.  Tried the following encodings: %s.'
+            % ', '.join([repr(enc) for enc in encodings if enc]))
+
+
+class Output(TransformSpec):
+
+    """
+    Abstract base class for output wrappers.
+    """
+
+    component_type = 'output'
+
+    default_destination_path = None
+
+    def __init__(self, settings=None, destination=None, destination_path=None,
+                 encoding=None):
+        self.encoding = encoding
+        """The character encoding for the output destination."""
+
+        if settings:
+            if not encoding:
+                self.encoding = settings.output_encoding
+            import warnings, traceback
+            warnings.warn(
+                'Setting output encoding via a "settings" struct is '
+                'deprecated; send encoding directly instead.\n%s'
+                % ''.join(traceback.format_list(traceback.extract_stack()
+                                                [-3:-1])))
+
+        self.destination = destination
+        """The destination for output data."""
+
+        self.destination_path = destination_path
+        """A text reference to the destination."""
+
+        if not destination_path:
+            self.destination_path = self.default_destination_path
+
+    def __repr__(self):
+        return ('%s: destination=%r, destination_path=%r'
+                % (self.__class__, self.destination, self.destination_path))
+
+    def write(self, data):
+        raise NotImplementedError
+
+    def encode(self, data):
+        if self.encoding and self.encoding.lower() == 'unicode':
+            return data
+        else:
+            return data.encode(self.encoding or '')
+
+
+class FileInput(Input):
+
+    """
+    Input for single, simple file-like objects.
+    """
+
+    def __init__(self, settings=None, source=None, source_path=None,
+                 encoding=None, autoclose=1):
+        """
+        :Parameters:
+            - `source`: either a file-like object (which is read directly), or
+              `None` (which implies `sys.stdin` if no `source_path` given).
+            - `source_path`: a path to a file, which is opened and then read.
+            - `autoclose`: close automatically after read (boolean); always
+              false if `sys.stdin` is the source.
+        """
+        Input.__init__(self, settings, source, source_path, encoding)
+        self.autoclose = autoclose
+        if source is None:
+            if source_path:
+                self.source = open(source_path)
+            else:
+                self.source = sys.stdin
+                self.autoclose = None
+        if not source_path:
+            try:
+                self.source_path = self.source.name
+            except AttributeError:
+                pass
+
+    def read(self):
+        """Read and decode a single file and return the data."""
+        data = self.source.read()
+        if self.autoclose:
+            self.close()
+        return self.decode(data)
+
+    def close(self):
+        self.source.close()
+
+
+class FileOutput(Output):
+
+    """
+    Output for single, simple file-like objects.
+    """
+
+    def __init__(self, settings=None, destination=None, destination_path=None,
+                 encoding=None, autoclose=1):
+        """
+        :Parameters:
+            - `destination`: either a file-like object (which is written
+              directly) or `None` (which implies `sys.stdout` if no
+              `destination_path` given).
+            - `destination_path`: a path to a file, which is opened and then
+              written.
+            - `autoclose`: close automatically after write (boolean); always
+              false if `sys.stdout` is the destination.
+        """
+        Output.__init__(self, settings, destination, destination_path,
+                        encoding)
+        self.opened = 1
+        self.autoclose = autoclose
+        if destination is None:
+            if destination_path:
+                self.opened = None
+            else:
+                self.destination = sys.stdout
+                self.autoclose = None
+        if not destination_path:
+            try:
+                self.destination_path = self.destination.name
+            except AttributeError:
+                pass
+
+    def open(self):
+        self.destination = open(self.destination_path, 'w')
+        self.opened = 1
+
+    def write(self, data):
+        """Encode `data`, write it to a single file, and return it."""
+        output = self.encode(data)
+        if not self.opened:
+            self.open()
+        self.destination.write(output)
+        if self.autoclose:
+            self.close()
+        return output
+
+    def close(self):
+        self.destination.close()
+        self.opened = None
+
+
+class StringInput(Input):
+
+    """
+    Direct string input.
+    """
+
+    default_source_path = '<string>'
+
+    def read(self):
+        """Decode and return the source string."""
+        return self.decode(self.source)
+
+
+class StringOutput(Output):
+
+    """
+    Direct string output.
+    """
+
+    default_destination_path = '<string>'
+
+    def write(self, data):
+        """Encode `data`, store it in `self.destination`, and return it."""
+        self.destination = self.encode(data)
+        return self.destination
+
+
+class NullInput(Input):
+
+    """
+    Degenerate input: read nothing.
+    """
+
+    default_source_path = 'null input'
+
+    def read(self):
+        """Return a null string."""
+        return u''
+
+
+class NullOutput(Output):
+
+    """
+    Degenerate output: write nothing.
+    """
+
+    default_destination_path = 'null output'
+
+    def write(self, data):
+        """Do nothing ([don't even] send data to the bit bucket)."""
+        pass

lib/python/docutils/languages/__init__.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:02 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+This package contains modules for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+_languages = {}
+
+def get_language(language_code):
+    if _languages.has_key(language_code):
+        return _languages[language_code]
+    module = __import__(language_code, globals(), locals())
+    _languages[language_code] = module
+    return module

lib/python/docutils/languages/de.py

+# Authors:   David Goodger; Gunnar Schwant
+# Contact:   goodger@users.sourceforge.net
+# Revision:  $Revision: 1.2 $
+# Date:      $Date: 2003/02/01 09:26:03 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+German language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+from docutils import nodes
+
+
+labels = {
+    'author': 'Autor',
+    'authors': 'Autoren',
+    'organization': 'Organisation',
+    'address': 'Adresse',
+    'contact': 'Kontakt',
+    'version': 'Version',
+    'revision': 'Revision',
+    'status': 'Status',
+    'date': 'Datum',
+    'dedication': 'Widmung',
+    'copyright': 'Copyright',
+    'abstract': 'Zusammenfassung',
+    'attention': 'Achtung!',
+    'caution': 'Vorsicht!',
+    'danger': '!GEFAHR!',
+    'error': 'Fehler',
+    'hint': 'Hinweis',
+    'important': 'Wichtig',
+    'note': 'Bemerkung',
+    'tip': 'Tipp',
+    'warning': 'Warnung',
+    'contents': 'Inhalt'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+    'autor': nodes.author,
+    'autoren': nodes.authors,
+    'organisation': nodes.organization,
+    'adresse': nodes.address,
+    'kontakt': nodes.contact,
+    'version': nodes.version,
+    'revision': nodes.revision,
+    'status': nodes.status,
+    'datum': nodes.date,
+    'copyright': nodes.copyright,
+    'widmung': nodes.topic,
+    'zusammenfassung': nodes.topic}
+"""Field name (lowcased) to node class name mapping for bibliographic fields
+(field_list)."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

lib/python/docutils/languages/en.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:03 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+English-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+from docutils import nodes
+
+
+labels = {
+      'author': 'Author',
+      'authors': 'Authors',
+      'organization': 'Organization',
+      'address': 'Address',
+      'contact': 'Contact',
+      'version': 'Version',
+      'revision': 'Revision',
+      'status': 'Status',
+      'date': 'Date',
+      'copyright': 'Copyright',
+      'dedication': 'Dedication',
+      'abstract': 'Abstract',
+      'attention': 'Attention!',
+      'caution': 'Caution!',
+      'danger': '!DANGER!',
+      'error': 'Error',
+      'hint': 'Hint',
+      'important': 'Important',
+      'note': 'Note',
+      'tip': 'Tip',
+      'warning': 'Warning',
+      'contents': 'Contents'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      'author': nodes.author,
+      'authors': nodes.authors,
+      'organization': nodes.organization,
+      'address': nodes.address,
+      'contact': nodes.contact,
+      'version': nodes.version,
+      'revision': nodes.revision,
+      'status': nodes.status,
+      'date': nodes.date,
+      'copyright': nodes.copyright,
+      'dedication': nodes.topic,
+      'abstract': nodes.topic}
+"""Field name (lowcased) to node class name mapping for bibliographic fields
+(field_list)."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

lib/python/docutils/languages/fr.py

+# Author: Stefane Fermigier
+# Contact: sf@fermigier.com
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:03 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+French-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+from docutils import nodes
+
+
+labels = {
+      'author': 'Auteur',
+      'authors': 'Auteurs',
+      'organization': 'Organisation',
+      'address': 'Adresse',
+      'contact': 'Contact',
+      'version': 'Version',
+      'revision': 'R\u00e9vision',
+      'status': 'Statut',
+      'date': 'Date',
+      'copyright': 'Copyright',
+      'dedication': 'D\u00e9dicace',
+      'abstract': 'R\u00e9sum\u00e9',
+      'attention': 'Attention!',
+      'caution': 'Avertissement!',
+      'danger': '!DANGER!',
+      'error': 'Erreur',
+      'hint': 'Indication',
+      'important': 'Important',
+      'note': 'Note',
+      'tip': 'Astuce',
+      'warning': 'Avertissement',
+      'contents': 'Contenu'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      'auteur': nodes.author,
+      'auteurs': nodes.authors,
+      'organisation': nodes.organization,
+      'adresse': nodes.address,
+      'contact': nodes.contact,
+      'version': nodes.version,
+      'r\u00e9vision': nodes.revision,
+      'status': nodes.status,
+      'date': nodes.date,
+      'copyright': nodes.copyright,
+      'd\u00e9dicace': nodes.topic,
+      'r\u00e9sum\u00e9': nodes.topic}
+"""Field name (lowcased) to node class name mapping for bibliographic fields
+(field_list)."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

lib/python/docutils/languages/it.py

+# Author: Nicola Larosa
+# Contact: docutils@tekNico.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:03 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Italian-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+from docutils import nodes
+
+
+labels = {
+      'author': 'Autore',
+      'authors': 'Autori',
+      'organization': 'Organizzazione',
+      'address': 'Indirizzo',
+      'contact': 'Contatti',
+      'version': 'Versione',
+      'revision': 'Revisione',
+      'status': 'Status',
+      'date': 'Data',
+      'copyright': 'Copyright',
+      'dedication': 'Dedica',
+      'abstract': 'Riassunto',
+      'attention': 'Attenzione!',
+      'caution': 'Cautela!',
+      'danger': '!PERICOLO!',
+      'error': 'Errore',
+      'hint': 'Suggerimento',
+      'important': 'Importante',
+      'note': 'Nota',
+      'tip': 'Consiglio',
+      'warning': 'Avvertenza',
+      'contents': 'Indice'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      'autore': nodes.author,
+      'autori': nodes.authors,
+      'organizzazione': nodes.organization,
+      'indirizzo': nodes.address,
+      'contatti': nodes.contact,
+      'versione': nodes.version,
+      'revisione': nodes.revision,
+      'status': nodes.status,
+      'data': nodes.date,
+      'copyright': nodes.copyright,
+      'dedica': nodes.topic,
+      'riassunto': nodes.topic}
+"""Field name (lowcased) to node class name mapping for bibliographic fields
+(field_list)."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

lib/python/docutils/languages/sk.py

+# :Author: Miroslav Vasko
+# :Contact: zemiak@zoznam.sk
+# :Revision: $Revision: 1.2 $
+# :Date: $Date: 2003/02/01 09:26:03 $
+# :Copyright: This module has been placed in the public domain.
+
+"""
+Slovak-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+from docutils import nodes
+
+
+labels = {
+      'author': u'Autor',
+      'authors': u'Autori',
+      'organization': u'Organiz\u00E1cia',
+      'address': u'Adresa',
+      'contact': u'Kontakt',
+      'version': u'Verzia',
+      'revision': u'Rev\u00EDzia',
+      'status': u'Stav',
+      'date': u'D\u00E1tum',
+      'copyright': u'Copyright',
+      'dedication': u'Venovanie',
+      'abstract': u'Abstraktne',
+      'attention': u'Pozor!',
+      'caution': u'Opatrne!',
+      'danger': u'!NEBEZPE\u010cENSTVO!',
+      'error': u'Chyba',
+      'hint': u'Rada',
+      'important': u'D\u00F4le\u017Eit\u00E9',
+      'note': u'Pozn\u00E1mka',
+      'tip': u'Tip',
+      'warning': u'Varovanie',
+      'contents': u'Obsah'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      u'autor': nodes.author,
+      u'autori': nodes.authors,
+      u'organiz\u00E1cia': nodes.organization,
+      u'adresa': nodes.address,
+      u'kontakt': nodes.contact,
+      u'verzia': nodes.version,
+      u'rev\u00EDzia': nodes.revision,
+      u'stav': nodes.status,
+      u'D\u00E1tum': nodes.date,
+      u'copyright': nodes.copyright,
+      u'venovanie': nodes.topic,
+      u'abstraktne': nodes.topic}
+"""Field name (lowcased) to node class name mapping for bibliographic fields
+(field_list)."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

lib/python/docutils/languages/sv.py

+# Author:    Adam Chodorowski
+# Contact:   chodorowski@users.sourceforge.net
+# Revision:  $Revision: 1.2 $
+# Date:      $Date: 2003/02/01 09:26:03 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Swedish language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+from docutils import nodes
+
+
+labels = {
+    'author':       u'F\u00f6rfattare',
+    'authors':      u'F\u00f6rfattare',
+    'organization': u'Organisation',
+    'address':      u'Adress',
+    'contact':      u'Kontakt',
+    'version':      u'Version',
+    'revision':     u'Revision',
+    'status':       u'Status',
+    'date':         u'Datum',
+    'copyright':    u'Copyright',
+    'dedication':   u'Dedikation',
+    'abstract':     u'Sammanfattning',
+    'attention':    u'Observera!',
+    'caution':      u'Varning!',
+    'danger':       u'FARA!',
+    'error':        u'Fel',
+    'hint':         u'V\u00e4gledning',
+    'important':    u'Viktigt',
+    'note':         u'Notera',
+    'tip':          u'Tips',
+    'warning':      u'Varning',
+    'contents':     u'Inneh\u00e5ll' }
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+    # 'Author' and 'Authors' identical in Swedish; assume the plural:
+    u'f\u00f6rfattare': nodes.authors,
+    u'organisation':    nodes.organization,
+    u'adress':          nodes.address,
+    u'kontakt':         nodes.contact,
+    u'version':         nodes.version,
+    u'revision':        nodes.revision,
+    u'status':          nodes.status,
+    u'datum':           nodes.date,
+    u'copyright':       nodes.copyright,
+    u'dedikation':      nodes.topic, 
+    u'sammanfattning':  nodes.topic }
+"""Field name (lowcased) to node class name mapping for bibliographic fields
+(field_list)."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

lib/python/docutils/nodes.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:00 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Docutils document tree element class library.
+
+Classes in CamelCase are abstract base classes or auxiliary classes. The one
+exception is `Text`, for a text (PCDATA) node; uppercase is used to
+differentiate from element classes.  Classes in lower_case_with_underscores
+are element classes, matching the XML element generic identifiers in the DTD_.
+
+The position of each node (the level at which it can occur) is significant and
+is represented by abstract base classes (`Root`, `Structural`, `Body`,
+`Inline`, etc.).  Certain transformations will be easier because we can use
+``isinstance(node, base_class)`` to determine the position of the node in the
+hierarchy.
+
+.. _DTD: http://docutils.sourceforge.net/spec/docutils.dtd
+"""
+
+__docformat__ = 'reStructuredText'
+
+import sys
+import os
+import re
+import xml.dom.minidom
+from types import IntType, SliceType, StringType, UnicodeType, \
+     TupleType, ListType
+from UserString import UserString
+
+
+# ==============================
+#  Functional Node Base Classes
+# ==============================
+
+class Node:
+
+    """Abstract base class of nodes in a document tree."""
+
+    parent = None
+    """Back-reference to the Node immediately containing this Node."""
+
+    document = None
+    """The `document` node at the root of the tree containing this Node."""
+
+    source = None
+    """Path or description of the input source which generated this Node."""
+
+    line = None
+    """The line number (1-based) of the beginning of this Node in `source`."""
+
+    def __nonzero__(self):
+        """Node instances are always true."""
+        return 1
+
+    def asdom(self, dom=xml.dom.minidom):
+        """Return a DOM **fragment** representation of this Node."""
+        domroot = dom.Document()
+        return self._dom_node(domroot)
+
+    def pformat(self, indent='    ', level=0):
+        """Return an indented pseudo-XML representation, for test purposes."""
+        raise NotImplementedError
+
+    def copy(self):
+        """Return a copy of self."""
+        raise NotImplementedError
+
+    def setup_child(self, child):
+        child.parent = self
+        if self.document:
+            child.document = self.document
+            if child.source is None:
+                child.source = self.document.current_source
+            if child.line is None:
+                child.line = self.document.current_line
+
+    def walk(self, visitor):
+        """
+        Traverse a tree of `Node` objects, calling ``visit_...`` methods of
+        `visitor` when entering each node. If there is no
+        ``visit_particular_node`` method for a node of type
+        ``particular_node``, the ``unknown_visit`` method is called.  (The
+        `walkabout()` method is similar, except it also calls ``depart_...``
+        methods before exiting each node.)
+
+        This tree traversal supports limited in-place tree
+        modifications.  Replacing one node with one or more nodes is
+        OK, as is removing an element.  However, if the node removed
+        or replaced occurs after the current node, the old node will
+        still be traversed, and any new nodes will not.
+
+        Within ``visit_...`` methods (and ``depart_...`` methods for
+        `walkabout()`), `TreePruningException` subclasses may be raised
+        (`SkipChildren`, `SkipSiblings`, `SkipNode`, `SkipDeparture`).
+
+        Parameter `visitor`: A `NodeVisitor` object, containing a
+        ``visit_...`` method for each `Node` subclass encountered.
+        """
+        name = 'visit_' + self.__class__.__name__
+        method = getattr(visitor, name, visitor.unknown_visit)
+        visitor.document.reporter.debug(name, category='nodes.Node.walk')
+        try:
+            method(self)
+        except (SkipChildren, SkipNode):
+            return
+        except SkipDeparture:           # not applicable; ignore
+            pass
+        children = self.get_children()
+        try:
+            for child in children[:]:
+                child.walk(visitor)
+        except SkipSiblings:
+            pass
+
+    def walkabout(self, visitor):
+        """
+        Perform a tree traversal similarly to `Node.walk()` (which see),
+        except also call ``depart_...`` methods before exiting each node. If
+        there is no ``depart_particular_node`` method for a node of type
+        ``particular_node``, the ``unknown_departure`` method is called.
+
+        Parameter `visitor`: A `NodeVisitor` object, containing ``visit_...``
+        and ``depart_...`` methods for each `Node` subclass encountered.
+        """
+        call_depart = 1
+        name = 'visit_' + self.__class__.__name__
+        method = getattr(visitor, name, visitor.unknown_visit)
+        visitor.document.reporter.debug(name, category='nodes.Node.walkabout')
+        try:
+            try:
+                method(self)
+            except SkipNode:
+                return
+            except SkipDeparture:
+                call_depart = 0
+            children = self.get_children()
+            try:
+                for child in children[:]:
+                    child.walkabout(visitor)
+            except SkipSiblings:
+                pass
+        except SkipChildren:
+            pass
+        if call_depart:
+            name = 'depart_' + self.__class__.__name__
+            method = getattr(visitor, name, visitor.unknown_departure)
+            visitor.document.reporter.debug(
+                  name, category='nodes.Node.walkabout')
+            method(self)
+
+
+class Text(Node, UserString):
+
+    """
+    Instances are terminal nodes (leaves) containing text only; no child
+    nodes or attributes.  Initialize by passing a string to the constructor.
+    Access the text itself with the `astext` method.
+    """
+
+    tagname = '#text'
+
+    def __init__(self, data, rawsource=''):
+        UserString.__init__(self, data)
+
+        self.rawsource = rawsource
+        """The raw text from which this element was constructed."""
+
+    def __repr__(self):
+        data = repr(self.data)
+        if len(data) > 70:
+            data = repr(self.data[:64] + ' ...')
+        return '<%s: %s>' % (self.tagname, data)
+
+    def shortrepr(self):
+        data = repr(self.data)
+        if len(data) > 20:
+            data = repr(self.data[:16] + ' ...')
+        return '<%s: %s>' % (self.tagname, data)
+
+    def _dom_node(self, domroot):
+        return domroot.createTextNode(self.data)
+
+    def astext(self):
+        return self.data
+
+    def copy(self):
+        return self.__class__(self.data)
+
+    def pformat(self, indent='    ', level=0):
+        result = []
+        indent = indent * level
+        for line in self.data.splitlines():
+            result.append(indent + line + '\n')
+        return ''.join(result)
+
+    def get_children(self):
+        """Text nodes have no children. Return []."""
+        return []
+
+
+class Element(Node):
+
+    """
+    `Element` is the superclass to all specific elements.
+
+    Elements contain attributes and child nodes.  Elements emulate
+    dictionaries for attributes, indexing by attribute name (a string).  To
+    set the attribute 'att' to 'value', do::
+
+        element['att'] = 'value'
+
+    Elements also emulate lists for child nodes (element nodes and/or text
+    nodes), indexing by integer.  To get the first child node, use::
+
+        element[0]
+
+    Elements may be constructed using the ``+=`` operator.  To add one new
+    child node to element, do::
+
+        element += node
+
+    This is equivalent to ``element.append(node)``.
+
+    To add a list of multiple child nodes at once, use the same ``+=``
+    operator::
+
+        element += [node1, node2]
+
+    This is equivalent to ``element.extend([node1, node2])``.
+    """
+
+    tagname = None
+    """The element generic identifier. If None, it is set as an instance
+    attribute to the name of the class."""
+
+    child_text_separator = '\n\n'
+    """Separator for child nodes, used by `astext()` method."""
+
+    def __init__(self, rawsource='', *children, **attributes):
+        self.rawsource = rawsource
+        """The raw text from which this element was constructed."""
+
+        self.children = []
+        """List of child nodes (elements and/or `Text`)."""
+
+        self.extend(children)           # maintain parent info
+
+        self.attributes = {}
+        """Dictionary of attribute {name: value}."""
+
+        for att, value in attributes.items():
+            self.attributes[att.lower()] = value
+
+        if self.tagname is None:
+            self.tagname = self.__class__.__name__
+
+    def _dom_node(self, domroot):
+        element = domroot.createElement(self.tagname)
+        for attribute, value in self.attributes.items():
+            if type(value) is ListType:
+                value = ' '.join(value)
+            element.setAttribute(attribute, str(value))
+        for child in self.children:
+            element.appendChild(child._dom_node(domroot))
+        return element
+
+    def __repr__(self):
+        data = ''
+        for c in self.children:
+            data += c.shortrepr()
+            if len(data) > 60:
+                data = data[:56] + ' ...'
+                break
+        if self.hasattr('name'):
+            return '<%s "%s": %s>' % (self.__class__.__name__,
+                                      self.attributes['name'], data)
+        else:
+            return '<%s: %s>' % (self.__class__.__name__, data)
+
+    def shortrepr(self):
+        if self.hasattr('name'):
+            return '<%s "%s"...>' % (self.__class__.__name__,
+                                      self.attributes['name'])
+        else:
+            return '<%s...>' % self.tagname
+
+    def __str__(self):
+        if self.children:
+            return '%s%s%s' % (self.starttag(),
+                                ''.join([str(c) for c in self.children]),
+                                self.endtag())
+        else:
+            return self.emptytag()
+
+    def starttag(self):
+        parts = [self.tagname]
+        for name, value in self.attlist():
+            if value is None:           # boolean attribute
+                parts.append(name)
+            elif isinstance(value, ListType):
+                values = [str(v) for v in value]
+                parts.append('%s="%s"' % (name, ' '.join(values)))
+            else:
+                parts.append('%s="%s"' % (name, str(value)))
+        return '<%s>' % ' '.join(parts)
+
+    def endtag(self):
+        return '</%s>' % self.tagname
+
+    def emptytag(self):
+        return '<%s/>' % ' '.join([self.tagname] +
+                                  ['%s="%s"' % (n, v)
+                                   for n, v in self.attlist()])
+
+    def __len__(self):
+        return len(self.children)
+
+    def __getitem__(self, key):
+        if isinstance(key, UnicodeType) or isinstance(key, StringType):
+            return self.attributes[key]
+        elif isinstance(key, IntType):
+            return self.children[key]
+        elif isinstance(key, SliceType):
+            assert key.step in (None, 1), 'cannot handle slice with stride'
+            return self.children[key.start:key.stop]
+        else:
+            raise TypeError, ('element index must be an integer, a slice, or '
+                              'an attribute name string')
+
+    def __setitem__(self, key, item):
+        if isinstance(key, UnicodeType) or isinstance(key, StringType):
+            self.attributes[str(key)] = item
+        elif isinstance(key, IntType):
+            self.setup_child(item)
+            self.children[key] = item
+        elif isinstance(key, SliceType):
+            assert key.step in (None, 1), 'cannot handle slice with stride'
+            for node in item:
+                self.setup_child(node)
+            self.children[key.start:key.stop] = item
+        else:
+            raise TypeError, ('element index must be an integer, a slice, or '
+                              'an attribute name string')
+
+    def __delitem__(self, key):
+        if isinstance(key, UnicodeType) or isinstance(key, StringType):
+            del self.attributes[key]
+        elif isinstance(key, IntType):
+            del self.children[key]
+        elif isinstance(key, SliceType):
+            assert key.step in (None, 1), 'cannot handle slice with stride'
+            del self.children[key.start:key.stop]
+        else:
+            raise TypeError, ('element index must be an integer, a simple '
+                              'slice, or an attribute name string')
+
+    def __add__(self, other):
+        return self.children + other
+
+    def __radd__(self, other):
+        return other + self.children
+
+    def __iadd__(self, other):
+        """Append a node or a list of nodes to `self.children`."""
+        if isinstance(other, Node):
+            self.setup_child(other)
+            self.children.append(other)
+        elif other is not None:
+            for node in other:
+                self.setup_child(node)
+            self.children.extend(other)
+        return self
+
+    def astext(self):
+        return self.child_text_separator.join(
+              [child.astext() for child in self.children])
+
+    def attlist(self):
+        attlist = self.attributes.items()
+        attlist.sort()
+        return attlist
+
+    def get(self, key, failobj=None):
+        return self.attributes.get(key, failobj)
+
+    def hasattr(self, attr):
+        return self.attributes.has_key(attr)
+
+    def delattr(self, attr):
+        if self.attributes.has_key(attr):
+            del self.attributes[attr]
+
+    def setdefault(self, key, failobj=None):
+        return self.attributes.setdefault(key, failobj)
+
+    has_key = hasattr
+
+    def append(self, item):
+        self.setup_child(item)
+        self.children.append(item)
+
+    def extend(self, item):
+        for node in item:
+            self.setup_child(node)
+        self.children.extend(item)
+
+    def insert(self, index, item):
+        if isinstance(item, Node):
+            self.setup_child(item)
+            self.children.insert(index, item)
+        elif item is not None:
+            self[index:index] = item
+
+    def pop(self, i=-1):
+        return self.children.pop(i)
+
+    def remove(self, item):
+        self.children.remove(item)
+
+    def index(self, item):
+        return self.children.index(item)
+
+    def replace(self, old, new):
+        """Replace one child `Node` with another child or children."""
+        index = self.index(old)
+        if isinstance(new, Node):
+            self.setup_child(new)
+            self[index] = new
+        elif new is not None:
+            self[index:index+1] = new
+
+    def first_child_matching_class(self, childclass, start=0, end=sys.maxint):
+        """
+        Return the index of the first child whose class exactly matches.
+
+        Parameters:
+
+        - `childclass`: A `Node` subclass to search for, or a tuple of `Node`
+          classes. If a tuple, any of the classes may match.
+        - `start`: Initial index to check.
+        - `end`: Initial index to *not* check.
+        """
+        if not isinstance(childclass, TupleType):
+            childclass = (childclass,)
+        for index in range(start, min(len(self), end)):
+            for c in childclass:
+                if isinstance(self[index], c):
+                    return index
+        return None
+
+    def first_child_not_matching_class(self, childclass, start=0,
+                                       end=sys.maxint):
+        """
+        Return the index of the first child whose class does *not* match.
+
+        Parameters:
+
+        - `childclass`: A `Node` subclass to skip, or a tuple of `Node`
+          classes. If a tuple, none of the classes may match.
+        - `start`: Initial index to check.
+        - `end`: Initial index to *not* check.
+        """
+        if not isinstance(childclass, TupleType):
+            childclass = (childclass,)
+        for index in range(start, min(len(self), end)):
+            match = 0
+            for c in childclass:
+                if isinstance(self.children[index], c):
+                    match = 1
+                    break
+            if not match:
+                return index
+        return None
+
+    def pformat(self, indent='    ', level=0):
+        return ''.join(['%s%s\n' % (indent * level, self.starttag())] +
+                       [child.pformat(indent, level+1)
+                        for child in self.children])
+
+    def get_children(self):
+        """Return this element's children."""
+        return self.children
+
+    def copy(self):
+        return self.__class__(**self.attributes)
+
+    def set_class(self, name):
+        """Add a new name to the "class" attribute."""
+        self.attributes['class'] = (self.attributes.get('class', '') + ' '
+                                    + name.lower()).strip()
+
+
+class TextElement(Element):
+
+    """
+    An element which directly contains text.
+
+    Its children are all Text or TextElement nodes.
+    """
+
+    child_text_separator = ''
+    """Separator for child nodes, used by `astext()` method."""
+
+    def __init__(self, rawsource='', text='', *children, **attributes):
+        if text != '':
+            textnode = Text(text)
+            Element.__init__(self, rawsource, textnode, *children,
+                              **attributes)
+        else:
+            Element.__init__(self, rawsource, *children, **attributes)
+
+
+class FixedTextElement(TextElement):
+
+    """An element which directly contains preformatted text."""
+
+    def __init__(self, rawsource='', text='', *children, **attributes):
+        TextElement.__init__(self, rawsource, text, *children, **attributes)
+        self.attributes['xml:space'] = 'preserve'
+
+
+# ========
+#  Mixins
+# ========
+
+class Resolvable:
+
+    resolved = 0
+
+
+class BackLinkable:
+
+    def add_backref(self, refid):
+        self.setdefault('backrefs', []).append(refid)
+
+
+# ====================
+#  Element Categories
+# ====================
+
+class Root: pass
+
+class Titular: pass
+
+class PreDecorative:
+    """Category of Node which may occur before Decorative Nodes."""
+
+class PreBibliographic(PreDecorative):
+    """Category of Node which may occur before Bibliographic Nodes."""
+
+class Bibliographic(PreDecorative): pass
+
+class Decorative: pass
+
+class Structural: pass
+
+class Body: pass
+
+class General(Body): pass
+
+class Sequential(Body): pass
+
+class Admonition(Body): pass
+
+class Special(Body):
+    """Special internal body elements."""
+
+class Invisible:
+    """Internal elements that don't appear in output."""
+
+class Part: pass
+
+class Inline: pass
+
+class Referential(Resolvable): pass
+
+class Targetable(Resolvable):
+
+    referenced = 0
+
+class Labeled:
+    """Contains a `label` as its first element."""
+
+
+# ==============
+#  Root Element
+# ==============
+
+class document(Root, Structural, Element):
+
+    def __init__(self, settings, reporter, *args, **kwargs):
+        Element.__init__(self, *args, **kwargs)
+
+        self.current_source = None
+        """Path to or description of the input source being processed."""
+
+        self.current_line = None
+        """Line number (1-based) of `current_source`."""
+
+        self.settings = settings
+        """Runtime settings data record."""
+
+        self.reporter = reporter
+        """System message generator."""
+
+        self.external_targets = []
+        """List of external target nodes."""
+
+        self.internal_targets = []
+        """List of internal target nodes."""
+
+        self.indirect_targets = []
+        """List of indirect target nodes."""
+
+        self.substitution_defs = {}
+        """Mapping of substitution names to substitution_definition nodes."""
+
+        self.refnames = {}
+        """Mapping of names to lists of referencing nodes."""
+
+        self.refids = {}
+        """Mapping of ids to lists of referencing nodes."""
+
+        self.nameids = {}
+        """Mapping of names to unique id's."""
+
+        self.nametypes = {}
+        """Mapping of names to hyperlink type (boolean: True => explicit,
+        False => implicit."""
+
+        self.ids = {}
+        """Mapping of ids to nodes."""
+
+        self.substitution_refs = {}
+        """Mapping of substitution names to lists of substitution_reference
+        nodes."""
+
+        self.footnote_refs = {}
+        """Mapping of footnote labels to lists of footnote_reference nodes."""
+
+        self.citation_refs = {}
+        """Mapping of citation labels to lists of citation_reference nodes."""
+
+        self.anonymous_targets = []
+        """List of anonymous target nodes."""
+
+        self.anonymous_refs = []
+        """List of anonymous reference nodes."""
+
+        self.autofootnotes = []
+        """List of auto-numbered footnote nodes."""
+
+        self.autofootnote_refs = []
+        """List of auto-numbered footnote_reference nodes."""
+
+        self.symbol_footnotes = []
+        """List of symbol footnote nodes."""
+
+        self.symbol_footnote_refs = []
+        """List of symbol footnote_reference nodes."""
+
+        self.footnotes = []
+        """List of manually-numbered footnote nodes."""
+
+        self.citations = []
+        """List of citation nodes."""
+
+        self.autofootnote_start = 1
+        """Initial auto-numbered footnote number."""
+
+        self.symbol_footnote_start = 0
+        """Initial symbol footnote symbol index."""
+
+        self.id_start = 1
+        """Initial ID number."""
+
+        self.parse_messages = []
+        """System messages generated while parsing."""
+
+        self.transform_messages = []
+        """System messages generated while applying transforms."""
+
+        import docutils.transforms
+        self.transformer = docutils.transforms.Transformer(self)
+        """Storage for transforms to be applied to this document."""
+
+        self.document = self
+
+    def asdom(self, dom=xml.dom.minidom):
+        """Return a DOM representation of this document."""
+        domroot = dom.Document()
+        domroot.appendChild(self._dom_node(domroot))
+        return domroot
+
+    def set_id(self, node, msgnode=None):
+        if node.has_key('id'):
+            id = node['id']
+            if self.ids.has_key(id) and self.ids[id] is not node:
+                msg = self.reporter.severe('Duplicate ID: "%s".' % id)
+                if msgnode != None:
+                    msgnode += msg
+        else:
+            if node.has_key('name'):
+                id = make_id(node['name'])
+            else:
+                id = ''
+            while not id or self.ids.has_key(id):
+                id = 'id%s' % self.id_start
+                self.id_start += 1
+            node['id'] = id
+        self.ids[id] = node
+        return id
+
+    def set_name_id_map(self, node, id, msgnode=None, explicit=None):
+        """
+        `self.nameids` maps names to IDs, while `self.nametypes` maps names to
+        booleans representing hyperlink type (True==explicit,
+        False==implicit).  This method updates the mappings.
+
+        The following state transition table shows how `self.nameids` ("ids")
+        and `self.nametypes` ("types") change with new input (a call to this
+        method), and what actions are performed:
+
+        ====  =====  ========  ========  =======  ====  =====  =====
+         Old State    Input          Action        New State   Notes
+        -----------  --------  -----------------  -----------  -----
+        ids   types  new type  sys.msg.  dupname  ids   types
+        ====  =====  ========  ========  =======  ====  =====  =====
+        --    --     explicit  --        --       new   True
+        --    --     implicit  --        --       new   False
+        None  False  explicit  --        --       new   True
+        old   False  explicit  implicit  old      new   True
+        None  True   explicit  explicit  new      None  True
+        old   True   explicit  explicit  new,old  None  True   [#]_
+        None  False  implicit  implicit  new      None  False
+        old   False  implicit  implicit  new,old  None  False
+        None  True   implicit  implicit  new      None  True
+        old   True   implicit  implicit  new      old   True
+        ====  =====  ========  ========  =======  ====  =====  =====
+
+        .. [#] Do not clear the name-to-id map or invalidate the old target if
+           both old and new targets are external and refer to identical URIs.
+           The new target is invalidated regardless.
+        """
+        if node.has_key('name'):
+            name = node['name']
+            if self.nameids.has_key(name):
+                self.set_duplicate_name_id(node, id, name, msgnode, explicit)
+            else:
+                self.nameids[name] = id
+                self.nametypes[name] = explicit
+
+    def set_duplicate_name_id(self, node, id, name, msgnode, explicit):
+        old_id = self.nameids[name]
+        old_explicit = self.nametypes[name]
+        self.nametypes[name] = old_explicit or explicit
+        if explicit:
+            if old_explicit:
+                level = 2
+                if old_id is not None:
+                    old_node = self.ids[old_id]
+                    if node.has_key('refuri'):
+                        refuri = node['refuri']
+                        if old_node.has_key('name') \
+                               and old_node.has_key('refuri') \
+                               and old_node['refuri'] == refuri:
+                            level = 1   # just inform if refuri's identical
+                    if level > 1:
+                        dupname(old_node)
+                        self.nameids[name] = None
+                msg = self.reporter.system_message(
+                    level, 'Duplicate explicit target name: "%s".' % name,
+                    backrefs=[id], base_node=node)
+                if msgnode != None:
+                    msgnode += msg
+                dupname(node)
+            else:
+                self.nameids[name] = id
+                if old_id is not None:
+                    old_node = self.ids[old_id]
+                    dupname(old_node)
+        else:
+            if old_id is not None and not old_explicit:
+                self.nameids[name] = None
+                old_node = self.ids[old_id]
+                dupname(old_node)
+            dupname(node)
+        if not explicit or (not old_explicit and old_id is not None):
+            msg = self.reporter.info(
+                'Duplicate implicit target name: "%s".' % name,
+                backrefs=[id], base_node=node)
+            if msgnode != None:
+                msgnode += msg
+
+    def has_name(self, name):
+        return self.nameids.has_key(name)
+
+    def note_implicit_target(self, target, msgnode=None):
+        id = self.set_id(target, msgnode)
+        self.set_name_id_map(target, id, msgnode, explicit=None)
+
+    def note_explicit_target(self, target, msgnode=None):
+        id = self.set_id(target, msgnode)
+        self.set_name_id_map(target, id, msgnode, explicit=1)
+
+    def note_refname(self, node):
+        self.refnames.setdefault(node['refname'], []).append(node)
+
+    def note_refid(self, node):
+        self.refids.setdefault(node['refid'], []).append(node)
+
+    def note_external_target(self, target):
+        self.external_targets.append(target)
+
+    def note_internal_target(self, target):
+        self.internal_targets.append(target)
+
+    def note_indirect_target(self, target):
+        self.indirect_targets.append(target)
+        if target.has_key('name'):
+            self.note_refname(target)
+
+    def note_anonymous_target(self, target):
+        self.set_id(target)
+        self.anonymous_targets.append(target)
+
+    def note_anonymous_ref(self, ref):
+        self.anonymous_refs.append(ref)
+
+    def note_autofootnote(self, footnote):
+        self.set_id(footnote)
+        self.autofootnotes.append(footnote)
+
+    def note_autofootnote_ref(self, ref):
+        self.set_id(ref)
+        self.autofootnote_refs.append(ref)
+
+    def note_symbol_footnote(self, footnote):
+        self.set_id(footnote)
+        self.symbol_footnotes.append(footnote)
+
+    def note_symbol_footnote_ref(self, ref):
+        self.set_id(ref)
+        self.symbol_footnote_refs.append(ref)
+
+    def note_footnote(self, footnote):
+        self.set_id(footnote)
+        self.footnotes.append(footnote)
+
+    def note_footnote_ref(self, ref):
+        self.set_id(ref)
+        self.footnote_refs.setdefault(ref['refname'], []).append(ref)
+        self.note_refname(ref)
+
+    def note_citation(self, citation):
+        self.citations.append(citation)
+
+    def note_citation_ref(self, ref):
+        self.set_id(ref)
+        self.citation_refs.setdefault(ref['refname'], []).append(ref)
+        self.note_refname(ref)
+
+    def note_substitution_def(self, subdef, msgnode=None):
+        name = subdef['name']
+        if self.substitution_defs.has_key(name):
+            msg = self.reporter.error(
+                  'Duplicate substitution definition name: "%s".' % name,
+                  base_node=subdef)
+            if msgnode != None:
+                msgnode += msg
+            oldnode = self.substitution_defs[name]
+            dupname(oldnode)
+        # keep only the last definition
+        self.substitution_defs[name] = subdef
+
+    def note_substitution_ref(self, subref):
+        self.substitution_refs.setdefault(
+              subref['refname'], []).append(subref)
+
+    def note_pending(self, pending, priority=None):
+        self.transformer.add_pending(pending, priority)
+
+    def note_parse_message(self, message):
+        self.parse_messages.append(message)
+
+    def note_transform_message(self, message):
+        self.transform_messages.append(message)
+
+    def note_source(self, source, offset):
+        self.current_source = source
+        if offset is None:
+            self.current_line = offset
+        else:
+            self.current_line = offset + 1
+
+    def copy(self):
+        return self.__class__(self.settings, self.reporter,
+                              **self.attributes)
+
+
+# ================
+#  Title Elements
+# ================
+
+class title(Titular, PreBibliographic, TextElement): pass
+class subtitle(Titular, PreBibliographic, TextElement): pass
+
+
+# ========================
+#  Bibliographic Elements
+# ========================
+
+class docinfo(Bibliographic, Element): pass
+class author(Bibliographic, TextElement): pass
+class authors(Bibliographic, Element): pass
+class organization(Bibliographic, TextElement): pass
+class address(Bibliographic, FixedTextElement): pass
+class contact(Bibliographic, TextElement): pass
+class version(Bibliographic, TextElement): pass
+class revision(Bibliographic, TextElement): pass
+class status(Bibliographic, TextElement): pass
+class date(Bibliographic, TextElement): pass
+class copyright(Bibliographic, TextElement): pass
+
+
+# =====================
+#  Decorative Elements
+# =====================
+
+class decoration(Decorative, Element): pass
+class header(Decorative, Element): pass
+class footer(Decorative, Element): pass
+
+
+# =====================
+#  Structural Elements
+# =====================
+
+class section(Structural, Element): pass
+
+
+class topic(Structural, Element):
+
+    """
+    Topics are terminal, "leaf" mini-sections, like block quotes with titles,
+    or textual figures. A topic is just like a section, except that it has no
+    subsections, and it doesn't have to conform to section placement rules.
+
+    Topics are allowed wherever body elements (list, table, etc.) are allowed,
+    but only at the top level of a section or document. Topics cannot nest
+    inside topics or body elements; you can't have a topic inside a table,
+    list, block quote, etc.
+    """
+
+
+class transition(Structural, Element): pass
+
+
+# ===============
+#  Body Elements
+# ===============
+
+class paragraph(General, TextElement): pass
+class bullet_list(Sequential, Element): pass
+class enumerated_list(Sequential, Element): pass
+class list_item(Part, Element): pass
+class definition_list(Sequential, Element): pass
+class definition_list_item(Part, Element): pass
+class term(Part, TextElement): pass
+class classifier(Part, TextElement): pass
+class definition(Part, Element): pass
+class field_list(Sequential, Element): pass
+class field(Part, Element): pass
+class field_name(Part, TextElement): pass
+class field_body(Part, Element): pass
+
+
+class option(Part, Element):
+
+    child_text_separator = ''
+
+
+class option_argument(Part, TextElement):
+
+    def astext(self):
+        return self.get('delimiter', ' ') + TextElement.astext(self)
+
+
+class option_group(Part, Element):
+
+    child_text_separator = ', '
+
+
+class option_list(Sequential, Element): pass
+
+
+class option_list_item(Part, Element):
+
+    child_text_separator = '  '
+
+
+class option_string(Part, TextElement): pass
+class description(Part, Element): pass
+class literal_block(General, FixedTextElement): pass
+class doctest_block(General, FixedTextElement): pass
+class line_block(General, FixedTextElement): pass
+class block_quote(General, Element): pass
+class attention(Admonition, Element): pass
+class caution(Admonition, Element): pass
+class danger(Admonition, Element): pass
+class error(Admonition, Element): pass
+class important(Admonition, Element): pass
+class note(Admonition, Element): pass
+class tip(Admonition, Element): pass
+class hint(Admonition, Element): pass
+class warning(Admonition, Element): pass
+class comment(Special, Invisible, PreBibliographic, FixedTextElement): pass
+class substitution_definition(Special, Invisible, TextElement): pass
+class target(Special, Invisible, Inline, TextElement, Targetable): pass
+class footnote(General, Element, Labeled, BackLinkable): pass
+class citation(General, Element, Labeled, BackLinkable): pass
+class label(Part, TextElement): pass
+class figure(General, Element): pass
+class caption(Part, TextElement): pass
+class legend(Part, Element): pass
+class table(General, Element): pass
+class tgroup(Part, Element): pass
+class colspec(Part, Element): pass
+class thead(Part, Element): pass
+class tbody(Part, Element): pass
+class row(Part, Element): pass
+class entry(Part, Element): pass
+
+
+class system_message(Special, PreBibliographic, Element, BackLinkable):
+
+    def __init__(self, message=None, *children, **attributes):
+        if message:
+            p = paragraph('', message)
+            children = (p,) + children
+        try:
+            Element.__init__(self, '', *children, **attributes)
+        except:
+            print 'system_message: children=%r' % (children,)
+            raise
+
+    def astext(self):
+        line = self.get('line', '')
+        return '%s:%s: (%s/%s) %s' % (self['source'], line, self['type'],
+                                      self['level'], Element.astext(self))
+
+
+class pending(Special, Invisible, PreBibliographic, Element):
+
+    """
+    The "pending" element is used to encapsulate a pending operation: the
+    operation (transform), the point at which to apply it, and any data it
+    requires.  Only the pending operation's location within the document is
+    stored in the public document tree (by the "pending" object itself); the
+    operation and its data are stored in the "pending" object's internal
+    instance attributes.
+
+    For example, say you want a table of contents in your reStructuredText
+    document.  The easiest way to specify where to put it is from within the
+    document, with a directive::
+
+        .. contents::
+
+    But the "contents" directive can't do its work until the entire document
+    has been parsed and possibly transformed to some extent.  So the directive
+    code leaves a placeholder behind that will trigger the second phase of the
+    its processing, something like this::
+
+        <pending ...public attributes...> + internal attributes
+
+    Use `document.note_pending()` so that the
+    `docutils.transforms.Transformer` stage of processing can run all pending
+    transforms.
+    """
+
+    def __init__(self, transform, details=None,
+                 rawsource='', *children, **attributes):
+        Element.__init__(self, rawsource, *children, **attributes)
+
+        self.transform = transform
+        """The `docutils.transforms.Transform` class implementing the pending
+        operation."""
+
+        self.details = details or {}
+        """Detail data (dictionary) required by the pending operation."""
+
+    def pformat(self, indent='    ', level=0):
+        internals = [
+              '.. internal attributes:',
+              '     .transform: %s.%s' % (self.transform.__module__,
+                                          self.transform.__name__),
+              '     .details:']
+        details = self.details.items()
+        details.sort()
+        for key, value in details:
+            if isinstance(value, Node):
+                internals.append('%7s%s:' % ('', key))
+                internals.extend(['%9s%s' % ('', line)
+                                  for line in value.pformat().splitlines()])
+            elif value and type(value) == ListType \
+                  and isinstance(value[0], Node):
+                internals.append('%7s%s:' % ('', key))
+                for v in value:
+                    internals.extend(['%9s%s' % ('', line)
+                                      for line in v.pformat().splitlines()])
+            else:
+                internals.append('%7s%s: %r' % ('', key, value))
+        return (Element.pformat(self, indent, level)
+                + ''.join([('    %s%s\n' % (indent * level, line))
+                           for line in internals]))
+
+    def copy(self):
+        return self.__class__(self.transform, self.details, self.rawsource,
+                              **self.attribuates)
+
+
+class raw(Special, Inline, PreBibliographic, FixedTextElement):
+
+    """
+    Raw data that is to be passed untouched to the Writer.
+    """
+
+    pass
+
+
+# =================
+#  Inline Elements
+# =================
+
+class emphasis(Inline, TextElement): pass
+class strong(Inline, TextElement): pass
+class literal(Inline, TextElement): pass
+class reference(Inline, Referential, TextElement): pass
+class footnote_reference(Inline, Referential, TextElement): pass
+class citation_reference(Inline, Referential, TextElement): pass
+class substitution_reference(Inline, TextElement): pass
+class title_reference(Inline, TextElement): pass
+class abbreviation(Inline, TextElement): pass
+class acronym(Inline, TextElement): pass
+
+
+class image(General, Inline, TextElement):
+
+    def astext(self):
+        return self.get('alt', '')
+
+
+class problematic(Inline, TextElement): pass
+class generated(Inline, TextElement): pass
+
+
+# ========================================
+#  Auxiliary Classes, Functions, and Data
+# ========================================
+
+node_class_names = """
+    Text
+    abbreviation acronym address attention author authors
+    block_quote bullet_list
+    caption caution citation citation_reference classifier colspec comment
+        contact copyright
+    danger date decoration definition definition_list definition_list_item
+        description docinfo doctest_block document
+    emphasis entry enumerated_list error
+    field field_body field_list field_name figure footer
+        footnote footnote_reference
+    generated
+    header hint
+    image important
+    label legend line_block list_item literal literal_block
+    note
+    option option_argument option_group option_list option_list_item
+        option_string organization
+    paragraph pending problematic
+    raw reference revision row
+    section status strong substitution_definition substitution_reference
+        subtitle system_message
+    table target tbody term tgroup thead tip title title_reference topic
+        transition
+    version
+    warning""".split()
+"""A list of names of all concrete Node subclasses."""
+
+
+class NodeVisitor:
+
+    """
+    "Visitor" pattern [GoF95]_ abstract superclass implementation for document
+    tree traversals.
+
+    Each node class has corresponding methods, doing nothing by default;
+    override individual methods for specific and useful behaviour.  The
+    "``visit_`` + node class name" method is called by `Node.walk()` upon
+    entering a node.  `Node.walkabout()` also calls the "``depart_`` + node
+    class name" method before exiting a node.
+
+    This is a base class for visitors whose ``visit_...`` & ``depart_...``
+    methods should be implemented for *all* node types encountered (such as
+    for `docutils.writers.Writer` subclasses).  Unimplemented methods will
+    raise exceptions.
+
+    For sparse traversals, where only certain node types are of interest,
+    subclass `SparseNodeVisitor` instead.  When (mostly or entirely) uniform
+    processing is desired, subclass `GenericNodeVisitor`.
+
+    .. [GoF95] Gamma, Helm, Johnson, Vlissides. *Design Patterns: Elements of
+       Reusable Object-Oriented Software*. Addison-Wesley, Reading, MA, USA,
+       1995.
+    """
+
+    def __init__(self, document):
+        self.document = document
+
+    def unknown_visit(self, node):
+        """
+        Called when entering unknown `Node` types.
+
+        Raise an exception unless overridden.
+        """
+        raise NotImplementedError('visiting unknown node type: %s'
+                                  % node.__class__.__name__)
+
+    def unknown_departure(self, node):
+        """
+        Called before exiting unknown `Node` types.
+
+        Raise exception unless overridden.
+        """
+        raise NotImplementedError('departing unknown node type: %s'
+                                  % node.__class__.__name__)
+
+
+class SparseNodeVisitor(NodeVisitor):
+
+    """
+    Base class for sparse traversals, where only certain node types are of
+    interest.  When ``visit_...`` & ``depart_...`` methods should be
+    implemented for *all* node types (such as for `docutils.writers.Writer`
+    subclasses), subclass `NodeVisitor` instead.
+    """
+
+    # Save typing with dynamic definitions.
+    for name in node_class_names:
+        exec """def visit_%s(self, node): pass\n""" % name
+        exec """def depart_%s(self, node): pass\n""" % name
+    del name
+
+
+class GenericNodeVisitor(NodeVisitor):
+
+    """
+    Generic "Visitor" abstract superclass, for simple traversals.
+
+    Unless overridden, each ``visit_...`` method calls `default_visit()`, and
+    each ``depart_...`` method (when using `Node.walkabout()`) calls
+    `default_departure()`. `default_visit()` (and `default_departure()`) must
+    be overridden in subclasses.
+
+    Define fully generic visitors by overriding `default_visit()` (and
+    `default_departure()`) only. Define semi-generic visitors by overriding
+    individual ``visit_...()`` (and ``depart_...()``) methods also.
+
+    `NodeVisitor.unknown_visit()` (`NodeVisitor.unknown_departure()`) should
+    be overridden for default behavior.
+    """
+
+    def default_visit(self, node):
+        """Override for generic, uniform traversals."""
+        raise NotImplementedError
+
+    def default_departure(self, node):
+        """Override for generic, uniform traversals."""
+        raise NotImplementedError
+
+    # Save typing with dynamic definitions.
+    for name in node_class_names:
+        exec """def visit_%s(self, node):
+                    self.default_visit(node)\n""" % name
+        exec """def depart_%s(self, node):
+                    self.default_departure(node)\n""" % name
+    del name
+
+
+class TreeCopyVisitor(GenericNodeVisitor):
+
+    """
+    Make a complete copy of a tree or branch, including element attributes.
+    """
+
+    def __init__(self, document):
+        GenericNodeVisitor.__init__(self, document)
+        self.parent_stack = []
+        self.parent = []
+
+    def get_tree_copy(self):
+        return self.parent[0]
+
+    def default_visit(self, node):
+        """Copy the current node, and make it the new acting parent."""
+        newnode = node.copy()
+        self.parent.append(newnode)
+        self.parent_stack.append(self.parent)
+        self.parent = newnode
+
+    def default_departure(self, node):
+        """Restore the previous acting parent."""
+        self.parent = self.parent_stack.pop()
+
+
+class TreePruningException(Exception):
+
+    """
+    Base class for `NodeVisitor`-related tree pruning exceptions.
+
+    Raise subclasses from within ``visit_...`` or ``depart_...`` methods
+    called from `Node.walk()` and `Node.walkabout()` tree traversals to prune
+    the tree traversed.
+    """
+
+    pass
+
+
+class SkipChildren(TreePruningException):
+
+    """
+    Do not visit any children of the current node.  The current node's
+    siblings and ``depart_...`` method are not affected.
+    """
+
+    pass
+
+
+class SkipSiblings(TreePruningException):
+
+    """
+    Do not visit any more siblings (to the right) of the current node.  The
+    current node's children and its ``depart_...`` method are not affected.
+    """
+
+    pass
+
+
+class SkipNode(TreePruningException):
+
+    """
+    Do not visit the current node's children, and do not call the current
+    node's ``depart_...`` method.
+    """
+
+    pass
+
+
+class SkipDeparture(TreePruningException):
+
+    """
+    Do not call the current node's ``depart_...`` method.  The current node's
+    children and siblings are not affected.
+    """
+
+    pass
+
+
+class NodeFound(TreePruningException):
+
+    """
+    Raise to indicate that the target of a search has been found.  This
+    exception must be caught by the client; it is not caught by the traversal
+    code.
+    """
+
+    pass
+
+
+def make_id(string):
+    """
+    Convert `string` into an identifier and return it.
+
+    Docutils identifiers will conform to the regular expression
+    ``[a-z][-a-z0-9]*``. For CSS compatibility, identifiers (the "class" and
+    "id" attributes) should have no underscores, colons, or periods. Hyphens
+    may be used.
+
+    - The `HTML 4.01 spec`_ defines identifiers based on SGML tokens:
+
+          ID and NAME tokens must begin with a letter ([A-Za-z]) and may be
+          followed by any number of letters, digits ([0-9]), hyphens ("-"),
+          underscores ("_"), colons (":"), and periods (".").
+
+    - However the `CSS1 spec`_ defines identifiers based on the "name" token,
+      a tighter interpretation ("flex" tokenizer notation; "latin1" and
+      "escape" 8-bit characters have been replaced with entities)::
+
+          unicode     \\[0-9a-f]{1,4}
+          latin1      [&iexcl;-&yuml;]
+          escape      {unicode}|\\[ -~&iexcl;-&yuml;]
+          nmchar      [-a-z0-9]|{latin1}|{escape}
+          name        {nmchar}+
+
+    The CSS1 "nmchar" rule does not include underscores ("_"), colons (":"),
+    or periods ("."), therefore "class" and "id" attributes should not contain
+    these characters. They should be replaced with hyphens ("-"). Combined
+    with HTML's requirements (the first character must be a letter; no
+    "unicode", "latin1", or "escape" characters), this results in the
+    ``[a-z][-a-z0-9]*`` pattern.
+
+    .. _HTML 4.01 spec: http://www.w3.org/TR/html401
+    .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1
+    """
+    id = _non_id_chars.sub('-', ' '.join(string.lower().split()))
+    id = _non_id_at_ends.sub('', id)
+    return str(id)
+
+_non_id_chars = re.compile('[^a-z0-9]+')
+_non_id_at_ends = re.compile('^[-0-9]+|-+$')
+
+def dupname(node):
+    node['dupname'] = node['name']
+    del node['name']

lib/python/docutils/optik.py

+# This is *not* the official distribution of Optik.  See
+# http://optik.sourceforge.net/ for the official distro.
+#
+# This combined module was converted from the "optik" package for Docutils use
+# by David Goodger (2002-06-12).  Optik is slated for inclusion in the Python
+# standard library as OptionParser.py.  Once Optik itself becomes a single
+# module, Docutils will include the official module and kill off this
+# temporary fork.
+
+"""optik
+
+A powerful, extensible, and easy-to-use command-line parser for Python.
+
+By Greg Ward <gward@python.net>
+
+See http://optik.sourceforge.net/
+"""
+
+# Copyright (c) 2001 Gregory P. Ward.  All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#   * Redistributions of source code must retain the above copyright
+#     notice, this list of conditions and the following disclaimer.
+#
+#   * Redistributions in binary form must reproduce the above copyright
+#     notice, this list of conditions and the following disclaimer in the
+#     documentation and/or other materials provided with the distribution.
+#
+#   * Neither the name of the author nor the names of its
+#     contributors may be used to endorse or promote products derived from
+#     this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+__revision__ = "$Id: optik.py,v 1.2 2003/02/01 09:26:00 andreasjung Exp $"
+
+__version__ = "1.3+"
+
+
+import sys
+import os
+from types import TupleType, ListType, DictType, StringType
+from distutils.fancy_getopt import wrap_text
+
+
+SUPPRESS_HELP = "SUPPRESS"+"HELP"
+SUPPRESS_USAGE = "SUPPRESS"+"USAGE"
+# Not supplying a default is different from a default of None,
+# so we need an explicit "not supplied" value.
+NO_DEFAULT = "NO"+"DEFAULT"
+
+
+class OptikError (Exception):
+    def __init__ (self, msg):
+        self.msg = msg
+
+    def __str__ (self):
+        return self.msg
+
+
+class OptionError (OptikError):
+    """
+    Raised if an Option instance is created with invalid or
+    inconsistent arguments.
+    """
+
+    def __init__ (self, msg, option):
+        self.msg = msg
+        self.option_id = str(option)
+
+    def __str__ (self):
+        if self.option_id:
+            return "option %s: %s" % (self.option_id, self.msg)
+        else:
+            return self.msg
+
+class OptionConflictError (OptionError):
+    """
+    Raised if conflicting options are added to an OptionParser.
+    """
+
+class OptionValueError (OptikError):
+    """
+    Raised if an invalid option value is encountered on the command
+    line.
+    """
+
+class BadOptionError (OptikError):
+    """
+    Raised if an invalid or ambiguous option is seen on the command-line.
+    """
+
+
+_builtin_cvt = { "int" : (int, "integer"),
+                 "long" : (long, "long integer"),
+                 "float" : (float, "floating-point"),
+                 "complex" : (complex, "complex") }
+
+def check_builtin (option, opt, value):
+    (cvt, what) = _builtin_cvt[option.type]
+    try:
+        return cvt(value)
+    except ValueError:
+        raise OptionValueError(
+            #"%s: invalid %s argument %r" % (opt, what, value))
+            "option %s: invalid %s value: %r" % (opt, what, value))
+
+def check_choice(option, opt, value):
+    if value in option.choices:
+        return value
+    else:
+        raise OptionValueError(
+            "option %s: invalid choice: %r (choose one of %r)"
+            % (opt, value, option.choices))
+
+
+class Option:
+    """
+    Instance attributes:
+      _short_opts : [string]
+      _long_opts : [string]
+
+      option_string : string
+        Set when help output is formatted.
+
+      action : string
+      type : string
+      dest : string
+      default : any
+      nargs : int
+      const : any
+      choices : [string]
+      callback : function
+      callback_args : (any*)
+      callback_kwargs : { string : any }
+      help : string
+      metavar : string
+    """
+
+    # The list of instance attributes that may be set through
+    # keyword args to the constructor.
+    ATTRS = ['action',
+             'type',
+             'dest',
+             'default',
+             'nargs',
+             'const',
+             'choices',
+             'callback',
+             'callback_args',
+             'callback_kwargs',
+             'help',
+             'metavar']
+
+    # The set of actions allowed by option parsers.  Explicitly listed
+    # here so the constructor can validate its arguments.
+    ACTIONS = ("store",
+               "store_const",
+               "store_true",
+               "store_false",
+               "append",
+               "count",
+               "callback",
+               "help",
+               "version")
+
+    # The set of actions that involve storing a value somewhere;
+    # also listed just for constructor argument validation.  (If
+    # the action is one of these, there must be a destination.)
+    STORE_ACTIONS = ("store",
+                     "store_const",
+                     "store_true",
+                     "store_false",
+                     "append",
+                     "count")
+
+    # The set of actions for which it makes sense to supply a value
+    # type, ie. where we expect an argument to this option.
+    TYPED_ACTIONS = ("store",
+                     "append",
+                     "callback")
+
+    # The set of known types for option parsers.  Again, listed here for
+    # constructor argument validation.
+    TYPES = ("string", "int", "long", "float", "complex", "choice")
+
+    # Dictionary of argument checking functions, which convert and
+    # validate option arguments according to the option type.
+    #
+    # Signature of checking functions is:
+    #   check(option : Option, opt : string, value : string) -> any
+    # where
+    #   option is the Option instance calling the checker
+    #   opt is the actual option seen on the command-line
+    #     (eg. "-a", "--file")
+    #   value is the option argument seen on the command-line
+    #
+    # The return value should be in the appropriate Python type
+    # for option.type -- eg. an integer if option.type == "int".
+    #
+    # If no checker is defined for a type, arguments will be
+    # unchecked and remain strings.
+    TYPE_CHECKER = { "int"    : check_builtin,
+                     "long"   : check_builtin,
+                     "float"  : check_builtin,
+                     "complex"  : check_builtin,
+                     "choice" : check_choice,
+                   }
+
+
+    # CHECK_METHODS is a list of unbound method objects; they are called
+    # by the constructor, in order, after all attributes are
+    # initialized.  The list is created and filled in later, after all
+    # the methods are actually defined.  (I just put it here because I
+    # like to define and document all class attributes in the same
+    # place.)  Subclasses that add another _check_*() method should
+    # define their own CHECK_METHODS list that adds their check method
+    # to those from this class.
+    CHECK_METHODS = None
+
+
+    # -- Constructor/initialization methods ----------------------------
+
+    def __init__ (self, *opts, **attrs):
+        # Set _short_opts, _long_opts attrs from 'opts' tuple
+        opts = self._check_opt_strings(opts)
+        self._set_opt_strings(opts)
+
+        # Set all other attrs (action, type, etc.) from 'attrs' dict
+        self._set_attrs(attrs)
+
+        # Check all the attributes we just set.  There are lots of
+        # complicated interdependencies, but luckily they can be farmed
+        # out to the _check_*() methods listed in CHECK_METHODS -- which
+        # could be handy for subclasses!  The one thing these all share
+        # is that they raise OptionError if they discover a problem.
+        for checker in self.CHECK_METHODS:
+            checker(self)
+
+    def _check_opt_strings (self, opts):
+        # Filter out None because early versions of Optik had exactly
+        # one short option and one long option, either of which
+        # could be None.
+        opts = filter(None, opts)
+        if not opts:
+            raise OptionError("at least one option string must be supplied",
+                              self)
+        return opts
+
+    def _set_opt_strings (self, opts):
+        self._short_opts = []
+        self._long_opts = []
+        for opt in opts:
+            if len(opt) < 2:
+                raise OptionError(
+                    "invalid option string %r: "
+                    "must be at least two characters long" % opt, self)
+            elif len(opt) == 2:
+                if not (opt[0] == "-" and opt[1] != "-"):
+                    raise OptionError(
+                        "invalid short option string %r: "
+                        "must be of the form -x, (x any non-dash char)" % opt,
+                        self)
+                self._short_opts.append(opt)
+            else:
+                if not (opt[0:2] == "--" and opt[2] != "-"):
+                    raise OptionError(
+                        "invalid long option string %r: "
+                        "must start with --, followed by non-dash" % opt,
+                        self)
+                self._long_opts.append(opt)
+
+    def _set_attrs (self, attrs):
+        for attr in self.ATTRS:
+            if attrs.has_key(attr):
+                setattr(self, attr, attrs[attr])
+                del attrs[attr]
+            else:
+                if attr == 'default':
+                    setattr(self, attr, NO_DEFAULT)
+                else:
+                    setattr(self, attr, None)
+        if attrs:
+            raise OptionError(
+                "invalid keyword arguments: %s" % ", ".join(attrs.keys()),
+                self)
+
+
+    # -- Constructor validation methods --------------------------------
+
+    def _check_action (self):
+        if self.action is None:
+            self.action = "store"
+        elif self.action not in self.ACTIONS:
+            raise OptionError("invalid action: %r" % self.action, self)
+
+    def _check_type (self):
+        if self.type is None:
+            # XXX should factor out another class attr here: list of
+            # actions that *require* a type
+            if self.action in ("store", "append"):
+                if self.choices is not None:
+                    # The "choices" attribute implies "choice" type.
+                    self.type = "choice"
+                else:
+                    # No type given?  "string" is the most sensible default.
+                    self.type = "string"
+        else:
+            if self.type not in self.TYPES:
+                raise OptionError("invalid option type: %r" % self.type, self)
+            if self.action not in self.TYPED_ACTIONS:
+                raise OptionError(
+                    "must not supply a type for action %r" % self.action, self)
+
+    def _check_choice(self):
+        if self.type == "choice":
+            if self.choices is None:
+                raise OptionError(
+                    "must supply a list of choices for type 'choice'", self)
+            elif type(self.choices) not in (TupleType, ListType):
+                raise OptionError(
+                    "choices must be a list of strings ('%s' supplied)"
+                    % str(type(self.choices)).split("'")[1], self)
+        elif self.choices is not None:
+            raise OptionError(
+                "must not supply choices for type %r" % self.type, self)
+
+    def _check_dest (self):
+        if self.action in self.STORE_ACTIONS and self.dest is None:
+            # No destination given, and we need one for this action.
+            # Glean a destination from the first long option string,
+            # or from the first short option string if no long options.
+            if self._long_opts:
+                # eg. "--foo-bar" -> "foo_bar"
+                self.dest = self._long_opts[0][2:].replace('-', '_')
+            else:
+                self.dest = self._short_opts[0][1]
+
+    def _check_const (self):
+        if self.action != "store_const" and self.const is not None:
+            raise OptionError(
+                "'const' must not be supplied for action %r" % self.action,
+                self)
+
+    def _check_nargs (self):
+        if self.action in self.TYPED_ACTIONS:
+            if self.nargs is None:
+                self.nargs = 1
+        elif self.nargs is not None:
+            raise OptionError(
+                "'nargs' must not be supplied for action %r" % self.action,
+                self)
+
+    def _check_callback (self):
+        if self.action == "callback":
+            if not callable(self.callback):
+                raise OptionError(
+                    "callback not callable: %r" % self.callback, self)
+            if (self.callback_args is not None and
+                type(self.callback_args) is not TupleType):
+                raise OptionError(
+                    "callback_args, if supplied, must be a tuple: not %r"
+                    % self.callback_args, self)
+            if (self.callback_kwargs is not None and
+                type(self.callback_kwargs) is not DictType):
+                raise OptionError(
+                    "callback_kwargs, if supplied, must be a dict: not %r"
+                    % self.callback_kwargs, self)
+        else:
+            if self.callback is not None:
+                raise OptionError(
+                    "callback supplied (%r) for non-callback option"
+                    % self.callback, self)
+            if self.callback_args is not None:
+                raise OptionError(
+                    "callback_args supplied for non-callback option", self)
+            if self.callback_kwargs is not None:
+                raise OptionError(
+                    "callback_kwargs supplied for non-callback option", self)
+
+
+    CHECK_METHODS = [_check_action,
+                     _check_type,
+                     _check_choice,
+                     _check_dest,
+                     _check_const,
+                     _check_nargs,
+                     _check_callback]
+
+
+    # -- Miscellaneous methods -----------------------------------------
+
+    def __str__ (self):
+        if self._short_opts or self._long_opts:
+            return "/".join(self._short_opts + self._long_opts)
+        else:
+            raise RuntimeError, "short_opts and long_opts both empty!"
+
+    def takes_value (self):
+        return self.type is not None
+
+
+    # -- Processing methods --------------------------------------------
+
+    def check_value (self, opt, value):
+        checker = self.TYPE_CHECKER.get(self.type)
+        if checker is None:
+            return value
+        else:
+            return checker(self, opt, value)
+
+    def process (self, opt, value, values, parser):
+
+        # First, convert the value(s) to the right type.  Howl if any
+        # value(s) are bogus.
+        if value is not None:
+            if self.nargs == 1:
+                value = self.check_value(opt, value)
+            else:
+                value = tuple([self.check_value(opt, v) for v in value])
+
+        # And then take whatever action is expected of us.
+        # This is a separate method to make life easier for
+        # subclasses to add new actions.
+        return self.take_action(
+            self.action, self.dest, opt, value, values, parser)
+
+    def take_action (self, action, dest, opt, value, values, parser):
+        if action == "store":
+            setattr(values, dest, value)
+        elif action == "store_const":
+            setattr(values, dest, self.const)
+        elif action == "store_true":
+            setattr(values, dest, 1)
+        elif action == "store_false":
+            setattr(values, dest, 0)
+        elif action == "append":
+            values.ensure_value(dest, []).append(value)
+        elif action == "count":
+            setattr(values, dest, values.ensure_value(dest, 0) + 1)
+        elif action == "callback":
+            args = self.callback_args or ()
+            kwargs = self.callback_kwargs or {}
+            self.callback(self, opt, value, parser, *args, **kwargs)
+        elif action == "help":
+            parser.print_help()
+            sys.exit(0)
+        elif action == "version":
+            parser.print_version()
+            sys.exit(0)
+        else:
+            raise RuntimeError, "unknown action %r" % self.action
+
+        return 1
+
+# class Option
+
+
+# Some day, there might be many Option classes.  As of Optik 1.3, the
+# preferred way to instantiate Options is indirectly, via make_option(),
+# which will become a factory function when there are many Option
+# classes.
+make_option = Option
+
+
+STD_HELP_OPTION = Option("-h", "--help",
+                         action="help",
+                         help="show this help message and exit")
+STD_VERSION_OPTION = Option("--version",
+                            action="version",
+                            help="show program's version number and exit")
+
+
+class OptionContainer:
+
+    """
+    Abstract base class.
+
+    Class attributes:
+      standard_option_list : [Option]
+        List of standard options that will be accepted by all instances
+        of this parser class (intended to be overridden by subclasses).
+
+    Instance attributes:
+      option_list : [Option]
+        The list of Option objects contained by this OptionContainer.
+      _short_opt : { string : Option }
+        Dictionary mapping short option strings, eg. "-f" or "-X",
+        to the Option instances that implement them.  If an Option
+        has multiple short option strings, it will appears in this
+        dictionary multiple times. [1]
+      _long_opt : { string : Option }
+        Dictionary mapping long option strings, eg. "--file" or
+        "--exclude", to the Option instances that implement them.
+        Again, a given Option can occur multiple times in this
+        dictionary. [1]
+      defaults : { string : any }
+        Dictionary mapping option destination names to default
+        values for each destination. [1]
+
+    [1] These mappings are common to (shared by) all components of the
+        controlling OptionParser, where they are initially created.
+
+    """
+
+    standard_option_list = []
+
+    def __init__(self, parser, description=None, option_list=None):
+        # List of Options is local to this OptionContainer.
+        self.option_list = []
+        # The shared mappings are stored in the parser.
+        self._short_opt = parser._short_opt
+        self._long_opt = parser._long_opt
+        self.defaults = parser.defaults
+        #
+        self.format = parser.format
+        self.option_class = parser.option_class
+        self.conflict_handler = parser.conflict_handler
+        self.set_description(description)
+        self._populate_option_list(option_list)
+
+    def set_description(self, description):
+        self.description = description
+
+    def _populate_option_list(self, option_list, version=None, help=None):
+        if self.standard_option_list:
+            self.add_options(self.standard_option_list)
+        if option_list:
+            self.add_options(option_list)
+        if version:
+            self.add_option(STD_VERSION_OPTION)
+        if help:
+            self.add_option(STD_HELP_OPTION)
+
+
+    # -- Option-adding methods -----------------------------------------
+
+    def _check_conflict (self, option):
+        conflict_opts = []
+        for opt in option._short_opts:
+            if self._short_opt.has_key(opt):
+                conflict_opts.append((opt, self._short_opt[opt]))
+        for opt in option._long_opts:
+            if self._long_opt.has_key(opt):
+                conflict_opts.append((opt, self._long_opt[opt]))
+
+        if conflict_opts:
+            handler = self.conflict_handler
+            if handler == "ignore":     # behaviour for Optik 1.0, 1.1
+                pass
+            elif handler == "error":    # new in 1.2
+                raise OptionConflictError(
+                    "conflicting option string(s): %s"
+                    % ", ".join([co[0] for co in conflict_opts]),
+                    option)
+            elif handler == "resolve":  # new in 1.2
+                for (opt, c_option) in conflict_opts:
+                    if opt.startswith("--"):
+                        c_option._long_opts.remove(opt)
+                        del self._long_opt[opt]
+                    else:
+                        c_option._short_opts.remove(opt)
+                        del self._short_opt[opt]
+                    if not (c_option._short_opts or c_option._long_opts):
+                        c_option.container.option_list.remove(c_option)
+
+    def add_option (self, *args, **kwargs):
+        """add_option(Option)
+           add_option(opt_str, ..., kwarg=val, ...)
+        """
+        if type(args[0]) is StringType:
+            option = self.option_class(*args, **kwargs)
+        elif len(args) == 1 and not kwargs:
+            option = args[0]
+            if not isinstance(option, Option):
+                raise TypeError, "not an Option instance: %r" % option
+        else:
+            raise TypeError, "invalid arguments"
+
+        self._check_conflict(option)
+
+        self.option_list.append(option)
+        option.container = self
+        for opt in option._short_opts:
+            self._short_opt[opt] = option
+        for opt in option._long_opts:
+            self._long_opt[opt] = option
+
+        if option.dest is not None:     # option has a dest, we need a default
+            if option.default is not NO_DEFAULT:
+                self.defaults[option.dest] = option.default
+            elif not self.defaults.has_key(option.dest):
+                self.defaults[option.dest] = None
+
+    def add_options (self, option_list):
+        for option in option_list:
+            self.add_option(option)
+
+    # -- Option query/removal methods ----------------------------------
+
+    def get_option (self, opt_str):
+        return (self._short_opt.get(opt_str) or
+                self._long_opt.get(opt_str))
+
+    def has_option (self, opt_str):
+        return (self._short_opt.has_key(opt_str) or
+                self._long_opt.has_key(opt_str))
+
+    def remove_option (self, opt_str):
+        option = self._short_opt.get(opt_str)
+        if option is None:
+            option = self._long_opt.get(opt_str)
+        if option is None:
+            raise ValueError("no such option %r" % opt_str)
+
+        for opt in option._short_opts:
+            del self._short_opt[opt]
+        for opt in option._long_opts:
+            del self._long_opt[opt]
+        option.container.option_list.remove(option)
+
+
+    # -- Feedback methods ----------------------------------------------
+
+    def get_option_help(self):
+        if not self.option_list:
+            return ""
+        result = []                     # list of strings to "".join() later
+        for option in self.option_list:
+            if not option.help is SUPPRESS_HELP:
+                result.append(self.format.format_option(option))
+        return "".join(result)
+
+    def get_description_help(self):
+        if self.description:
+            return self.format.format_description(self.description)
+        else:
+            return ""
+
+    def get_help(self):
+        result = ""
+        if self.description:
+            result = self.get_description_help() + "\n"
+        return result + self.get_option_help()
+
+
+class OptionGroup(OptionContainer):
+
+    def __init__(self, parser, title, description=None):
+        OptionContainer.__init__(self, parser, description)
+        self.parser = parser
+        self.title = title
+        self.description = description
+
+    def set_title(self, title):
+        self.title = title
+
+    def get_help(self):
+        result = self.format.format_heading(self.title)
+        self.format.increase_nesting()
+        result += OptionContainer.get_help(self)
+        self.format.decrease_nesting()
+        return result
+
+
+class Values:
+
+    def __init__ (self, defaults=None):
+        if defaults:
+            for (attr, val) in defaults.items():
+                setattr(self, attr, val)
+
+    def __repr__(self):
+        return "%s(%r)" % (self.__class__, self.__dict__)
+
+    def _update_careful (self, dict):
+        """
+        Update the option values from an arbitrary dictionary, but only
+        use keys from dict that already have a corresponding attribute
+        in self.  Any keys in dict without a corresponding attribute
+        are silently ignored.
+        """
+        for attr in dir(self):
+            if dict.has_key(attr):
+                dval = dict[attr]
+                if dval is not None:
+                    setattr(self, attr, dval)
+
+    def _update_loose (self, dict):
+        """
+        Update the option values from an arbitrary dictionary,
+        using all keys from the dictionary regardless of whether
+        they have a corresponding attribute in self or not.
+        """
+        self.__dict__.update(dict)
+
+    def _update (self, dict, mode):
+        if mode == "careful":
+            self._update_careful(dict)
+        elif mode == "loose":
+            self._update_loose(dict)
+        else:
+            raise ValueError, "invalid update mode: %r" % mode
+
+    def read_module (self, modname, mode="careful"):
+        __import__(modname)
+        mod = sys.modules[modname]
+        self._update(vars(mod), mode)
+
+    def read_file (self, filename, mode="careful"):
+        vars = {}
+        execfile(filename, vars)
+        self._update(vars, mode)
+
+    def ensure_value (self, attr, value):
+        if not hasattr(self, attr) or getattr(self, attr) is None:
+            setattr(self, attr, value)
+        return getattr(self, attr)
+
+
+class OptionParser(OptionContainer):
+
+    """
+    Instance attributes:
+      usage : string
+        a usage string for your program.  Before it is displayed
+        to the user, "%prog" will be expanded to the name of
+        your program (os.path.basename(sys.argv[0])).
+
+      allow_interspersed_args : boolean = true
+        If true, positional arguments may be interspersed with options.
+        Assuming -a and -b each take a single argument, the command-line
+          -ablah foo bar -bboo baz
+        will be interpreted the same as
+          -ablah -bboo -- foo bar baz
+        If this flag were false, that command line would be interpreted as
+          -ablah -- foo bar -bboo baz
+        -- ie. we stop processing options as soon as we see the first
+        non-option argument.  (This is the tradition followed by
+        Python's getopt module, Perl's Getopt::Std, and other argument-
+        parsing libraries, but it is generally annoying to users.)
+
+      rargs : [string]
+        the argument list currently being parsed.  Only set when
+        parse_args() is active, and continually trimmed down as
+        we consume arguments.  Mainly there for the benefit of
+        callback options.
+      largs : [string]
+        the list of leftover arguments that we have skipped while
+        parsing options.  If allow_interspersed_args is false, this
+        list is always empty.
+      values : Values
+        the set of option values currently being accumulated.  Only
+        set when parse_args() is active.  Also mainly for callbacks.
+
+    Because of the 'rargs', 'largs', and 'values' attributes,
+    OptionParser is not thread-safe.  If, for some perverse reason, you
+    need to parse command-line arguments simultaneously in different
+    threads, use different OptionParser instances.
+
+    """
+
+    def __init__ (self,
+                  usage=None,
+                  description=None,
+                  option_list=None,
+                  option_class=Option,
+                  version=None,
+                  help=1,
+                  conflict_handler="error",
+                  format=None):
+        """Override OptionContainer.__init__."""
+        self.set_usage(usage)
+        self.set_description(description)
+        self.option_class = option_class
+        self.version = version
+        self.set_conflict_handler(conflict_handler)
+        self.allow_interspersed_args = 1
+        if not format:
+            format = Indented()
+        self.format = format
+
+        # Create the various lists and dicts that constitute the
+        # "option list".  See class docstring for details about
+        # each attribute.
+        self._create_option_list()
+
+        # Populate the option list; initial sources are the
+        # standard_option_list class attribute, the 'option_list' argument,
+        # and the STD_VERSION_OPTION and STD_HELP_OPTION globals (if 'version'
+        # and/or 'help' supplied).
+        self._populate_option_list(option_list, version=version, help=help)
+
+        self._init_parsing_state()
+
+    # -- Private methods -----------------------------------------------
+    # (used by the constructor)
+
+    def _create_option_list (self):
+        self.option_list = []
+        self.option_groups = []
+        self._short_opt = {}            # single letter -> Option instance
+        self._long_opt = {}             # long option -> Option instance
+        self.defaults = {}              # maps option dest -> default value
+
+    def _init_parsing_state (self):
+        # These are set in parse_args() for the convenience of callbacks.
+        self.rargs = None
+        self.largs = None
+        self.values = None
+
+
+    # -- Simple modifier methods ---------------------------------------
+
+    def set_usage (self, usage):
+        if usage is None:
+            self.usage = "%prog [options]"
+        elif usage is SUPPRESS_USAGE:
+            self.usage = None
+        else:
+            self.usage = usage
+
+    def enable_interspersed_args (self):
+        self.allow_interspersed_args = 1
+
+    def disable_interspersed_args (self):
+        self.allow_interspersed_args = 0
+
+    def set_conflict_handler (self, handler):
+        if handler not in ("ignore", "error", "resolve"):
+            raise ValueError, "invalid conflict_resolution value %r" % handler
+        self.conflict_handler = handler
+
+    def set_default (self, dest, value):
+        self.defaults[dest] = value
+
+    def set_defaults (self, **kwargs):
+        self.defaults.update(kwargs)
+
+    def get_default_values(self):
+        return Values(self.defaults)
+
+
+    # -- OptionGroup methods -------------------------------------------
+
+    def add_option_group(self, group):
+        self.option_groups.append(group)
+
+    def get_option_group(self, opt_str):
+        option = (self._short_opt.get(opt_str) or
+                  self._long_opt.get(opt_str))
+        if option and option.container is not self:
+            return option.container
+        return None
+
+
+    # -- Option-parsing methods ----------------------------------------
+
+    def _get_args (self, args):
+        if args is None:
+            return sys.argv[1:]
+        else:
+            return args[:]              # don't modify caller's list
+
+    def parse_args (self, args=None, values=None):
+        """
+        parse_args(args : [string] = sys.argv[1:],
+                   values : Values = None)
+        -> (values : Values, args : [string])
+
+        Parse the command-line options found in 'args' (default:
+        sys.argv[1:]).  Any errors result in a call to 'error()', which
+        by default prints the usage message to stderr and calls
+        sys.exit() with an error message.  On success returns a pair
+        (values, args) where 'values' is an Values instance (with all
+        your option values) and 'args' is the list of arguments left
+        over after parsing options.
+        """
+        rargs = self._get_args(args)
+        if values is None:
+            values = self.get_default_values()
+
+        # Store the halves of the argument list as attributes for the
+        # convenience of callbacks:
+        #   rargs
+        #     the rest of the command-line (the "r" stands for
+        #     "remaining" or "right-hand")
+        #   largs
+        #     the leftover arguments -- ie. what's left after removing
+        #     options and their arguments (the "l" stands for "leftover"
+        #     or "left-hand")
+        self.rargs = rargs
+        self.largs = largs = []
+        self.values = values
+
+        try:
+            stop = self._process_args(largs, rargs, values)
+        except (BadOptionError, OptionValueError), err:
+            self.error(err.msg)
+
+        args = largs + rargs
+        return self.check_values(values, args)
+
+    def check_values (self, values, args):
+        """
+        check_values(values : Values, args : [string])
+        -> (values : Values, args : [string])
+
+        Check that the supplied option values and leftover arguments are
+        valid.  Returns the option values and leftover arguments
+        (possibly adjusted, possibly completely new -- whatever you
+        like).  Default implementation just returns the passed-in
+        values; subclasses may override as desired.
+        """
+        return (values, args)
+
+    def _process_args (self, largs, rargs, values):
+        """_process_args(largs : [string],
+                         rargs : [string],
+                         values : Values)
+
+        Process command-line arguments and populate 'values', consuming
+        options and arguments from 'rargs'.  If 'allow_interspersed_args' is
+        false, stop at the first non-option argument.  If true, accumulate any
+        interspersed non-option arguments in 'largs'.
+        """
+        while rargs:
+            arg = rargs[0]
+            # We handle bare "--" explicitly, and bare "-" is handled by the
+            # standard arg handler since the short arg case ensures that the
+            # len of the opt string is greater than 1.
+            if arg == "--":
+                del rargs[0]
+                return
+            elif arg[0:2] == "--":
+                # process a single long option (possibly with value(s))
+                self._process_long_opt(rargs, values)
+            elif arg[:1] == "-" and len(arg) > 1:
+                # process a cluster of short options (possibly with
+                # value(s) for the last one only)
+                self._process_short_opts(rargs, values)
+            elif self.allow_interspersed_args:
+                largs.append(arg)
+                del rargs[0]
+            else:
+                return                  # stop now, leave this arg in rargs
+
+        # Say this is the original argument list:
+        # [arg0, arg1, ..., arg(i-1), arg(i), arg(i+1), ..., arg(N-1)]
+        #                            ^
+        # (we are about to process arg(i)).
+        #
+        # Then rargs is [arg(i), ..., arg(N-1)] and largs is a *subset* of
+        # [arg0, ..., arg(i-1)] (any options and their arguments will have
+        # been removed from largs).
+        #
+        # The while loop will usually consume 1 or more arguments per pass.
+        # If it consumes 1 (eg. arg is an option that takes no arguments),
+        # then after _process_arg() is done the situation is:
+        #
+        #   largs = subset of [arg0, ..., arg(i)]
+        #   rargs = [arg(i+1), ..., arg(N-1)]
+        #
+        # If allow_interspersed_args is false, largs will always be
+        # *empty* -- still a subset of [arg0, ..., arg(i-1)], but
+        # not a very interesting subset!
+
+    def _match_long_opt (self, opt):
+        """_match_long_opt(opt : string) -> string
+
+        Determine which long option string 'opt' matches, ie. which one
+        it is an unambiguous abbrevation for.  Raises BadOptionError if
+        'opt' doesn't unambiguously match any long option string.
+        """
+        return _match_abbrev(opt, self._long_opt)
+
+    def _process_long_opt (self, rargs, values):
+        arg = rargs.pop(0)
+
+        # Value explicitly attached to arg?  Pretend it's the next
+        # argument.
+        if "=" in arg:
+            (opt, next_arg) = arg.split("=", 1)
+            rargs.insert(0, next_arg)
+            had_explicit_value = 1
+        else:
+            opt = arg
+            had_explicit_value = 0
+
+        opt = self._match_long_opt(opt)
+        option = self._long_opt[opt]
+        if option.takes_value():
+            nargs = option.nargs
+            if len(rargs) < nargs:
+                if nargs == 1:
+                    self.error("%s option requires a value" % opt)
+                else:
+                    self.error("%s option requires %d values"
+                               % (opt, nargs))
+            elif nargs == 1:
+                value = rargs.pop(0)
+            else:
+                value = tuple(rargs[0:nargs])
+                del rargs[0:nargs]
+
+        elif had_explicit_value:
+            self.error("%s option does not take a value" % opt)
+
+        else:
+            value = None
+
+        option.process(opt, value, values, self)
+
+    def _process_short_opts (self, rargs, values):
+        arg = rargs.pop(0)
+        stop = 0
+        i = 1
+        for ch in arg[1:]:
+            opt = "-" + ch
+            option = self._short_opt.get(opt)
+            i += 1                      # we have consumed a character
+
+            if not option:
+                self.error("no such option: %s" % opt)
+            if option.takes_value():
+                # Any characters left in arg?  Pretend they're the
+                # next arg, and stop consuming characters of arg.
+                if i < len(arg):
+                    rargs.insert(0, arg[i:])
+                    stop = 1
+
+                nargs = option.nargs
+                if len(rargs) < nargs:
+                    if nargs == 1:
+                        self.error("%s option requires a value" % opt)
+                    else:
+                        self.error("%s option requires %s values"
+                                   % (opt, nargs))
+                elif nargs == 1:
+                    value = rargs.pop(0)
+                else:
+                    value = tuple(rargs[0:nargs])
+                    del rargs[0:nargs]
+
+            else:                       # option doesn't take a value
+                value = None
+
+            option.process(opt, value, values, self)
+
+            if stop:
+                break
+
+
+    # -- Feedback methods ----------------------------------------------
+
+    def error (self, msg):
+        """error(msg : string)
+
+        Print a usage message incorporating 'msg' to stderr and exit.
+        If you override this in a subclass, it should not return -- it
+        should either exit or raise an exception.
+        """
+        self.print_usage(sys.stderr)
+        sys.exit("%s: error: %s" % (get_prog_name(), msg))
+
+    def get_usage_help(self):
+        if self.usage:
+            return self.format.format_usage(
+                self.usage.replace("%prog", get_prog_name()))
+        else:
+            return ""
+
+    def print_usage (self, file=None):
+        """print_usage(file : file = stdout)
+
+        Print the usage message for the current program (self.usage) to
+        'file' (default stdout).  Any occurence of the string "%prog" in
+        self.usage is replaced with the name of the current program
+        (basename of sys.argv[0]).  Does nothing if self.usage is empty
+        or not defined.
+        """
+        if self.usage:
+            print >>file, self.get_usage_help()
+
+    def get_version_help(self):
+        if self.version:
+            return self.version.replace("%prog", get_prog_name())
+        else:
+            return ""
+
+    def print_version (self, file=None):
+        """print_version(file : file = stdout)
+
+        Print the version message for this program (self.version) to
+        'file' (default stdout).  As with print_usage(), any occurence
+        of "%prog" in self.version is replaced by the current program's
+        name.  Does nothing if self.version is empty or undefined.
+        """
+        if self.version:
+            print >>file, self.get_version_help()
+
+    def get_option_help(self):
+        self.format.store_option_strings(self)
+        result = []
+        result.append(self.format.format_heading("Options"))
+        self.format.increase_nesting()
+        if self.option_list:
+            result.append(OptionContainer.get_option_help(self))
+            result.append("\n")
+        for group in self.option_groups:
+            result.append(group.get_help())
+            result.append("\n")
+        self.format.decrease_nesting()
+        # Drop the last "\n", or the header if no options or option groups:
+        return "".join(result[:-1])
+
+    def get_help(self):
+        result = []
+        if self.usage:
+            result.append(self.get_usage_help() + "\n")
+        if self.description:
+            result.append(self.get_description_help() + "\n")
+        result.append(self.get_option_help())
+        return "".join(result)
+
+    def print_help (self, file=None):
+        """print_help(file : file = stdout)
+
+        Print an extended help message, listing all options and any
+        help text provided with them, to 'file' (default stdout).
+        """
+        if file is None:
+            file = sys.stdout
+        file.write(self.get_help())
+
+# class OptionParser
+
+
+class HelpFormat:
+
+    """
+    "--help" output format; abstract base class (Strategy design pattern).
+
+    Instance attributes:
+      indent_increment : int
+        The number of columns to indent per nesting level.
+      max_help_position : int
+        The maximum starting column for option help text.
+      help_position : int
+        The calculated starting column for option help text;
+        initially the same as the maximum.
+      width : int
+        The overall width (in columns) for output.
+      current_indent : int
+        In columns, calculated.
+      level : int
+        Increased for each additional nesting level.
+      help_width : int
+        Number of columns available for option help text, calculated.
+    """
+
+    def __init__(self, indent_increment, max_help_position, width,
+                 short_first):
+        self.indent_increment = indent_increment
+        self.help_position = self.max_help_position = max_help_position
+        self.width = width
+        self.current_indent = 0
+        self.level = 0
+        self.help_width = width - max_help_position
+        if short_first:
+            self.format_option_strings = self.format_option_strings_short_first
+        else:
+            self.format_option_strings = self.format_option_strings_long_first
+
+    def increase_nesting(self):
+        self.current_indent += self.indent_increment
+        self.level += 1
+
+    def decrease_nesting(self):
+        self.current_indent -= self.indent_increment
+        assert self.current_indent >= 0, "Indent decreased below 0."
+        self.level -= 1
+
+    def format_usage(self, usage):
+        raise NotImplementedError
+
+    def format_heading(self, heading):
+        raise NotImplementedError
+
+    def format_description(self, description):
+        desc_width = self.width - self.current_indent
+        desc_lines = wrap_text(description, desc_width)
+        result = ["%*s%s\n" % (self.current_indent, "", line)
+                  for line in desc_lines]
+        return "".join(result)
+
+    def format_option(self, option):
+        # The help for each option consists of two parts:
+        #   * the opt strings and metavars
+        #     eg. ("-x", or "-fFILENAME, --file=FILENAME")
+        #   * the user-supplied help string
+        #     eg. ("turn on expert mode", "read data from FILENAME")
+        #
+        # If possible, we write both of these on the same line:
+        #   -x      turn on expert mode
+        #
+        # But if the opt string list is too long, we put the help
+        # string on a second line, indented to the same column it would
+        # start in if it fit on the first line.
+        #   -fFILENAME, --file=FILENAME
+        #           read data from FILENAME
+        result = []
+        opts = option.option_strings
+        opt_width = self.help_position - self.current_indent - 2
+        if len(opts) > opt_width:
+            opts = "%*s%s\n" % (self.current_indent, "", opts)
+            indent_first = self.help_position
+        else:                       # start help on same line as opts
+            opts = "%*s%-*s  " % (self.current_indent, "", opt_width, opts)
+            indent_first = 0
+        result.append(opts)
+        if option.help:
+            help_lines = wrap_text(option.help, self.help_width)
+            result.append("%*s%s\n" % (indent_first, "", help_lines[0]))
+            result.extend(["%*s%s\n" % (self.help_position, "", line)
+                           for line in help_lines[1:]])
+        elif opts[-1] != "\n":
+            result.append("\n")
+        return "".join(result)
+
+    def store_option_strings(self, parser):
+        self.increase_nesting()
+        max_len = 0
+        for opt in parser.option_list:
+            strings = self.format_option_strings(opt)
+            opt.option_strings = strings
+            max_len = max(max_len, len(strings) + self.current_indent)
+        self.increase_nesting()
+        for group in parser.option_groups:
+            for opt in group.option_list:
+                strings = self.format_option_strings(opt)
+                opt.option_strings = strings
+                max_len = max(max_len, len(strings) + self.current_indent)
+        self.decrease_nesting()
+        self.decrease_nesting()
+        self.help_position = min(max_len + 2, self.max_help_position)
+
+    def format_option_strings(self, option):
+        """Return a comma-separated list of option strigs & metavariables."""
+        raise NotImplementedError(
+            "Virtual method; use format_option_strings_short_first or "
+            "format_option_strings_long_first instead.")
+
+    def format_option_strings_short_first(self, option):
+        opts = []                       # list of "-a" or "--foo=FILE" strings
+        takes_value = option.takes_value()
+        if takes_value:
+            metavar = option.metavar or option.dest.upper()
+            for sopt in option._short_opts:
+                opts.append(sopt + metavar)
+            for lopt in option._long_opts:
+                opts.append(lopt + "=" + metavar)
+        else:
+            for opt in option._short_opts + option._long_opts:
+                opts.append(opt)
+        return ", ".join(opts)
+
+    def format_option_strings_long_first(self, option):
+        opts = []                       # list of "-a" or "--foo=FILE" strings
+        takes_value = option.takes_value()
+        if takes_value:
+            metavar = option.metavar or option.dest.upper()
+            for lopt in option._long_opts:
+                opts.append(lopt + "=" + metavar)
+            for sopt in option._short_opts:
+                opts.append(sopt + metavar)
+        else:
+            for opt in option._long_opts + option._short_opts:
+                opts.append(opt)
+        return ", ".join(opts)
+
+
+class Indented(HelpFormat):
+
+    """Formats help with indented section bodies."""
+
+    def __init__(self, indent_increment=2, max_help_position=24, width=78,
+                 short_first=1):
+        HelpFormat.__init__(self, indent_increment, max_help_position, width,
+                            short_first)
+
+    def format_usage(self, usage):
+        return "Usage: %s\n" % usage
+
+    def format_heading(self, heading):
+        return "%*s%s:\n" % (self.current_indent, "", heading)
+
+
+class Titled(HelpFormat):
+
+    """Formats help with underlined section headers."""
+
+    def __init__(self, indent_increment=0, max_help_position=24, width=78,
+                 short_first=None):
+        HelpFormat.__init__(self, indent_increment, max_help_position, width,
+                            short_first)
+
+    def format_usage(self, usage):
+        return "%s  %s\n" % (self.format_heading("Usage"), usage)
+
+    def format_heading(self, heading):
+        return "%s\n%s\n" % (heading, "=-"[self.level] * len(heading))
+
+
+def _match_abbrev (s, wordmap):
+    """_match_abbrev(s : string, wordmap : {string : Option}) -> string
+
+    Return the string key in 'wordmap' for which 's' is an unambiguous
+    abbreviation.  If 's' is found to be ambiguous or doesn't match any of
+    'words', raise BadOptionError.
+    """
+    # Is there an exact match?
+    if wordmap.has_key(s):
+        return s
+    else:
+        # Isolate all words with s as a prefix.
+        possibilities = [word for word in wordmap.keys()
+                         if word.startswith(s)]
+        # No exact match, so there had better be just one possibility.
+        if len(possibilities) == 1:
+            return possibilities[0]
+        elif not possibilities:
+            raise BadOptionError("no such option: %s" % s)
+        else:
+            # More than one possible completion: ambiguous prefix.
+            raise BadOptionError("ambiguous option: %s (%s?)"
+                                 % (s, ", ".join(possibilities)))
+
+def get_prog_name ():
+    return os.path.basename(sys.argv[0])

lib/python/docutils/parsers/__init__.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:05 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+This package contains Docutils parser modules.
+"""
+
+__docformat__ = 'reStructuredText'
+
+from docutils import Component
+
+
+class Parser(Component):
+
+    component_type = 'parser'
+
+    def parse(self, inputstring, document):
+        """Override to parse `inputstring` into document tree `document`."""
+        raise NotImplementedError('subclass must override this method')
+
+    def setup_parse(self, inputstring, document):
+        """Initial parse setup.  Call at start of `self.parse()`."""
+        self.inputstring = inputstring
+        self.document = document
+        document.reporter.attach_observer(document.note_parse_message)
+
+    def finish_parse(self):
+        """Finalize parse details.  Call at end of `self.parse()`."""
+        self.document.reporter.detach_observer(
+            self.document.note_parse_message)
+
+
+_parser_aliases = {
+      'restructuredtext': 'rst',
+      'rest': 'rst',
+      'restx': 'rst',
+      'rtxt': 'rst',}
+
+def get_parser_class(parser_name):
+    """Return the Parser class from the `parser_name` module."""
+    parser_name = parser_name.lower()
+    if _parser_aliases.has_key(parser_name):
+        parser_name = _parser_aliases[parser_name]
+    module = __import__(parser_name, globals(), locals())
+    return module.Parser

lib/python/docutils/parsers/rst/__init__.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:07 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+This is ``docutils.parsers.rst`` package. It exports a single class, `Parser`,
+the reStructuredText parser.
+
+
+Usage
+=====
+
+1. Create a parser::
+
+       parser = docutils.parsers.rst.Parser()
+
+   Several optional arguments may be passed to modify the parser's behavior.
+   Please see `Customizing the Parser`_ below for details.
+
+2. Gather input (a multi-line string), by reading a file or the standard
+   input::
+
+       input = sys.stdin.read()
+
+3. Create a new empty `docutils.nodes.document` tree::
+
+       document = docutils.utils.new_document(source, settings)
+
+   See `docutils.utils.new_document()` for parameter details.
+
+4. Run the parser, populating the document tree::
+
+       parser.parse(input, document)
+
+
+Parser Overview
+===============
+
+The reStructuredText parser is implemented as a state machine, examining its
+input one line at a time. To understand how the parser works, please first
+become familiar with the `docutils.statemachine` module, then see the
+`states` module.
+
+
+Customizing the Parser
+----------------------
+
+Anything that isn't already customizable is that way simply because that type
+of customizability hasn't been implemented yet.  Patches welcome!
+
+When instantiating an object of the `Parser` class, two parameters may be
+passed: ``rfc2822`` and ``inliner``.  Pass ``rfc2822=1`` to enable an initial
+RFC-2822 style header block, parsed as a "field_list" element (with "class"
+attribute set to "rfc2822").  Currently this is the only body-level element
+which is customizable without subclassing.  (Tip: subclass `Parser` and change
+its "state_classes" and "initial_state" attributes to refer to new classes.
+Contact the author if you need more details.)
+
+The ``inliner`` parameter takes an instance of `states.Inliner` or a subclass.
+It handles inline markup recognition.  A common extension is the addition of
+further implicit hyperlinks, like "RFC 2822".  This can be done by subclassing
+`states.Inliner`, adding a new method for the implicit markup, and adding a
+``(pattern, method)`` pair to the "implicit_dispatch" attribute of the
+subclass.  See `states.Inliner.implicit_inline()` for details.  Explicit
+inline markup can be customized in a `states.Inliner` subclass via the
+``patterns.initial`` and ``dispatch`` attributes (and new methods as
+appropriate).
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+import docutils.parsers
+import docutils.statemachine
+from docutils.parsers.rst import states
+
+
+class Parser(docutils.parsers.Parser):
+
+    """The reStructuredText parser."""
+
+    supported = ('restructuredtext', 'rst', 'rest', 'restx', 'rtxt', 'rstx')
+    """Aliases this parser supports."""
+
+    settings_spec = (
+        'reStructuredText Parser Options',
+        None,
+        (('Recognize and link to PEP references (like "PEP 258").',
+          ['--pep-references'],
+          {'action': 'store_true'}),
+         ('Recognize and link to RFC references (like "RFC 822").',
+          ['--rfc-references'],
+          {'action': 'store_true'}),
+         ('Set number of spaces for tab expansion (default 8).',
+          ['--tab-width'],
+          {'metavar': '<width>', 'type': 'int', 'default': 8}),))
+
+    def __init__(self, rfc2822=None, inliner=None):
+        if rfc2822:
+            self.initial_state = 'RFC2822Body'
+        else:
+            self.initial_state = 'Body'
+        self.state_classes = states.state_classes
+        self.inliner = inliner
+
+    def parse(self, inputstring, document):
+        """Parse `inputstring` and populate `document`, a document tree."""
+        self.setup_parse(inputstring, document)
+        debug = document.reporter[''].debug
+        self.statemachine = states.RSTStateMachine(
+              state_classes=self.state_classes,
+              initial_state=self.initial_state,
+              debug=debug)
+        inputlines = docutils.statemachine.string2lines(
+              inputstring, tab_width=document.settings.tab_width,
+              convert_whitespace=1)
+        self.statemachine.run(inputlines, document, inliner=self.inliner)
+        self.finish_parse()

lib/python/docutils/parsers/rst/directives/__init__.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:09 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+This package contains directive implementation modules.
+
+The interface for directive functions is as follows::
+
+    def directive_fn(name, arguments, options, content, lineno,
+                     content_offset, block_text, state, state_machine):
+        code...
+
+    # Set function attributes:
+    directive_fn.arguments = ...
+    directive_fn.options = ...
+    direcitve_fn.content = ...
+
+Parameters:
+
+- ``name`` is the directive type or name.
+
+- ``arguments`` is a list of positional arguments.
+
+- ``options`` is a dictionary mapping option names to values.
+
+- ``content`` is a list of strings, the directive content.
+
+- ``lineno`` is the line number of the first line of the directive.
+
+- ``content_offset`` is the line offset of the first line of the content from
+  the beginning of the current input.  Used when initiating a nested parse.
+
+- ``block_text`` is a string containing the entire directive.  Include it as
+  the content of a literal block in a system message if there is a problem.
+
+- ``state`` is the state which called the directive function.
+
+- ``state_machine`` is the state machine which controls the state which called
+  the directive function.
+
+Function attributes, interpreted by the directive parser (which calls the
+directive function):
+
+- ``arguments``: A 3-tuple specifying the expected positional arguments, or
+  ``None`` if the directive has no arguments.  The 3 items in the tuple are
+  ``(required, optional, whitespace OK in last argument)``:
+
+  1. The number of required arguments.
+  2. The number of optional arguments.
+  3. A boolean, indicating if the final argument may contain whitespace.
+
+  Arguments are normally single whitespace-separated words.  The final
+  argument may contain whitespace if the third item in the argument spec tuple
+  is 1/True.  If the form of the arguments is more complex, specify only one
+  argument (either required or optional) and indicate that final whitespace is
+  OK; the client code must do any context-sensitive parsing.
+
+- ``options``: A dictionary, mapping known option names to conversion
+  functions such as `int` or `float`.  ``None`` or an empty dict implies no
+  options to parse.
+
+- ``content``: A boolean; true if content is allowed.  Client code must handle
+  the case where content is required but not supplied (an empty content list
+  will be supplied).
+
+Directive functions return a list of nodes which will be inserted into the
+document tree at the point where the directive was encountered (can be an
+empty list).
+
+See `Creating reStructuredText Directives`_ for more information.
+
+.. _Creating reStructuredText Directives:
+   http://docutils.sourceforge.net/spec/howto/rst-directives.html
+"""
+
+__docformat__ = 'reStructuredText'
+
+from docutils import nodes
+from docutils.parsers.rst.languages import en as _fallback_language_module
+
+
+_directive_registry = {
+      'attention': ('admonitions', 'attention'),
+      'caution': ('admonitions', 'caution'),
+      'danger': ('admonitions', 'danger'),
+      'error': ('admonitions', 'error'),
+      'important': ('admonitions', 'important'),
+      'note': ('admonitions', 'note'),
+      'tip': ('admonitions', 'tip'),
+      'hint': ('admonitions', 'hint'),
+      'warning': ('admonitions', 'warning'),
+      'topic': ('body', 'topic'),
+      'line-block': ('body', 'line_block'),
+      'parsed-literal': ('body', 'parsed_literal'),
+      #'questions': ('body', 'question_list'),
+      'image': ('images', 'image'),
+      'figure': ('images', 'figure'),
+      'contents': ('parts', 'contents'),
+      'sectnum': ('parts', 'sectnum'),
+      #'footnotes': ('parts', 'footnotes'),
+      #'citations': ('parts', 'citations'),
+      'target-notes': ('references', 'target_notes'),
+      'meta': ('html', 'meta'),
+      #'imagemap': ('html', 'imagemap'),
+      'raw': ('misc', 'raw'),
+      'include': ('misc', 'include'),
+      'replace': ('misc', 'replace'),
+      'restructuredtext-test-directive': ('misc', 'directive_test_function'),}
+"""Mapping of directive name to (module name, function name).  The directive
+name is canonical & must be lowercase.  Language-dependent names are defined
+in the ``language`` subpackage."""
+
+_modules = {}
+"""Cache of imported directive modules."""
+
+_directives = {}
+"""Cache of imported directive functions."""
+
+def directive(directive_name, language_module, document):
+    """
+    Locate and return a directive function from its language-dependent name.
+    If not found in the current language, check English.  Return None if the
+    named directive cannot be found.
+    """
+    normname = directive_name.lower()
+    messages = []
+    msg_text = []
+    if _directives.has_key(normname):
+        return _directives[normname], messages
+    canonicalname = None
+    try:
+        canonicalname = language_module.directives[normname]
+    except AttributeError, error:
+        msg_text.append('Problem retrieving directive entry from language '
+                        'module %r: %s.' % (language_module, error))
+    except KeyError:
+        msg_text.append('No directive entry for "%s" in module "%s".'
+                        % (directive_name, language_module.__name__))
+    if not canonicalname:
+        try:
+            canonicalname = _fallback_language_module.directives[normname]
+            msg_text.append('Using English fallback for directive "%s".'
+                            % directive_name)
+        except KeyError:
+            msg_text.append('Trying "%s" as canonical directive name.'
+                            % directive_name)
+            # The canonical name should be an English name, but just in case:
+            canonicalname = normname
+    if msg_text:
+        message = document.reporter.info(
+            '\n'.join(msg_text), line=document.current_line)
+        messages.append(message)
+    try:
+        modulename, functionname = _directive_registry[canonicalname]
+    except KeyError:
+        return None, messages
+    if _modules.has_key(modulename):
+        module = _modules[modulename]
+    else:
+        try:
+            module = __import__(modulename, globals(), locals())
+        except ImportError:
+            return None, messages
+    try:
+        function = getattr(module, functionname)
+        _directives[normname] = function
+    except AttributeError:
+        return None, messages
+    return function, messages
+
+def flag(argument):
+    """
+    Check for a valid flag option (no argument) and return ``None``.
+
+    Raise ``ValueError`` if an argument is found.
+    """
+    if argument and argument.strip():
+        raise ValueError('no argument is allowed; "%s" supplied' % argument)
+    else:
+        return None
+
+def unchanged(argument):
+    """
+    Return the argument, unchanged.
+
+    Raise ``ValueError`` if no argument is found.
+    """
+    if argument is None:
+        raise ValueError('argument required but none supplied')
+    else:
+        return argument  # unchanged!
+
+def path(argument):
+    """
+    Return the path argument unwrapped (with newlines removed).
+
+    Raise ``ValueError`` if no argument is found or if the path contains
+    internal whitespace.
+    """
+    if argument is None:
+        raise ValueError('argument required but none supplied')
+    else:
+        path = ''.join([s.strip() for s in argument.splitlines()])
+        if path.find(' ') == -1:
+            return path
+        else:
+            raise ValueError('path contains whitespace')
+
+def nonnegative_int(argument):
+    """
+    Check for a nonnegative integer argument; raise ``ValueError`` if not.
+    """
+    value = int(argument)
+    if value < 0:
+        raise ValueError('negative value; must be positive or zero')
+    return value
+
+def format_values(values):
+    return '%s, or "%s"' % (', '.join(['"%s"' % s for s in values[:-1]]),
+                            values[-1])
+
+def choice(argument, values):
+    try:
+        value = argument.lower().strip()
+    except AttributeError:
+        raise ValueError('must supply an argument; choose from %s'
+                         % format_values(values))
+    if value in values:
+        return value
+    else:
+        raise ValueError('"%s" unknown; choose from %s'
+                         % (argument, format_values(values)))

lib/python/docutils/parsers/rst/directives/admonitions.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:09 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Admonition directives.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+from docutils.parsers.rst import states
+from docutils import nodes
+
+
+def admonition(node_class, name, arguments, options, content, lineno,
+               content_offset, block_text, state, state_machine):
+    text = '\n'.join(content)
+    admonition_node = node_class(text)
+    if text:
+        state.nested_parse(content, content_offset, admonition_node)
+        return [admonition_node]
+    else:
+        error = state_machine.reporter.error(
+            'The "%s" admonition is empty; content required.' % (name),
+            nodes.literal_block(block_text, block_text), line=lineno)
+        return [error]
+
+def attention(*args):
+    return admonition(nodes.attention, *args)
+
+attention.content = 1
+
+def caution(*args):
+    return admonition(nodes.caution, *args)
+
+caution.content = 1
+
+def danger(*args):
+    return admonition(nodes.danger, *args)
+
+danger.content = 1
+
+def error(*args):
+    return admonition(nodes.error, *args)
+
+error.content = 1
+
+def important(*args):
+    return admonition(nodes.important, *args)
+
+important.content = 1
+
+def note(*args):
+    return admonition(nodes.note, *args)
+
+note.content = 1
+
+def tip(*args):
+    return admonition(nodes.tip, *args)
+
+tip.content = 1
+
+def hint(*args):
+    return admonition(nodes.hint, *args)
+
+hint.content = 1
+
+def warning(*args):
+    return admonition(nodes.warning, *args)
+
+warning.content = 1

lib/python/docutils/parsers/rst/directives/body.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:09 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Directives for additional body elements.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+import sys
+from docutils import nodes
+
+
+def topic(name, arguments, options, content, lineno,
+          content_offset, block_text, state, state_machine):
+    if not state_machine.match_titles:
+        error = state_machine.reporter.error(
+              'Topics may not be nested within topics or body elements.',
+              nodes.literal_block(block_text, block_text), line=lineno)
+        return [error]
+    if not content:
+        warning = state_machine.reporter.warning(
+            'Content block expected for the "%s" directive; none found.'
+            % name, nodes.literal_block(block_text, block_text),
+            line=lineno)
+        return [warning]
+    title_text = arguments[0]
+    textnodes, messages = state.inline_text(title_text, lineno)
+    title = nodes.title(title_text, '', *textnodes)
+    text = '\n'.join(content)
+    topic_node = nodes.topic(text, title, *messages)
+    if text:
+        state.nested_parse(content, content_offset, topic_node)
+    return [topic_node]
+
+topic.arguments = (1, 0, 1)
+topic.content = 1
+
+def line_block(name, arguments, options, content, lineno,
+               content_offset, block_text, state, state_machine,
+               node_class=nodes.line_block):
+    if not content:
+        warning = state_machine.reporter.warning(
+            'Content block expected for the "%s" directive; none found.'
+            % name, nodes.literal_block(block_text, block_text), line=lineno)
+        return [warning]
+    text = '\n'.join(content)
+    text_nodes, messages = state.inline_text(text, lineno)
+    node = node_class(text, '', *text_nodes)
+    return [node] + messages
+
+line_block.content = 1
+
+def parsed_literal(name, arguments, options, content, lineno,
+                   content_offset, block_text, state, state_machine):
+    return line_block(name, arguments, options, content, lineno,
+                      content_offset, block_text, state, state_machine,
+                      node_class=nodes.literal_block)
+
+parsed_literal.content = 1

lib/python/docutils/parsers/rst/directives/html.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:09 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Directives for typically HTML-specific constructs.
+"""
+
+__docformat__ = 'reStructuredText'
+
+import sys
+from docutils import nodes, utils
+from docutils.parsers.rst import states
+from docutils.transforms import components
+
+
+def meta(name, arguments, options, content, lineno,
+         content_offset, block_text, state, state_machine):
+    node = nodes.Element()
+    if content:
+        new_line_offset, blank_finish = state.nested_list_parse(
+              content, content_offset, node, initial_state='MetaBody',
+              blank_finish=1, state_machine_kwargs=metaSMkwargs)
+        if (new_line_offset - content_offset) != len(content):
+            # incomplete parse of block?
+            error = state_machine.reporter.error(
+                'Invalid meta directive.',
+                nodes.literal_block(block_text, block_text), line=lineno)
+            node += error
+    else:
+        error = state_machine.reporter.error(
+            'Empty meta directive.',
+            nodes.literal_block(block_text, block_text), line=lineno)
+        node += error
+    return node.get_children()
+
+meta.content = 1
+
+def imagemap(name, arguments, options, content, lineno,
+             content_offset, block_text, state, state_machine):
+    return []
+
+
+class MetaBody(states.SpecializedBody):
+
+    class meta(nodes.Special, nodes.PreBibliographic, nodes.Element):
+        """HTML-specific "meta" element."""
+        pass
+
+    def field_marker(self, match, context, next_state):
+        """Meta element."""
+        node, blank_finish = self.parsemeta(match)
+        self.parent += node
+        return [], next_state, []
+
+    def parsemeta(self, match):
+        name = self.parse_field_marker(match)
+        indented, indent, line_offset, blank_finish = \
+              self.state_machine.get_first_known_indented(match.end())
+        node = self.meta()
+        pending = nodes.pending(components.Filter,
+                                {'component': 'writer',
+                                 'format': 'html',
+                                 'nodes': [node]})
+        node['content'] = ' '.join(indented)
+        if not indented:
+            line = self.state_machine.line
+            msg = self.reporter.info(
+                  'No content for meta tag "%s".' % name,
+                  nodes.literal_block(line, line),
+                  line=self.state_machine.abs_line_number())
+            return msg, blank_finish
+        tokens = name.split()
+        try:
+            attname, val = utils.extract_name_value(tokens[0])[0]
+            node[attname.lower()] = val
+        except utils.NameValueError:
+            node['name'] = tokens[0]
+        for token in tokens[1:]:
+            try:
+                attname, val = utils.extract_name_value(token)[0]
+                node[attname.lower()] = val
+            except utils.NameValueError, detail:
+                line = self.state_machine.line
+                msg = self.reporter.error(
+                      'Error parsing meta tag attribute "%s": %s.'
+                      % (token, detail), nodes.literal_block(line, line),
+                      line=self.state_machine.abs_line_number())
+                return msg, blank_finish
+        self.document.note_pending(pending)
+        return pending, blank_finish
+
+
+metaSMkwargs = {'state_classes': (MetaBody,)}

lib/python/docutils/parsers/rst/directives/images.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:09 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Directives for figures and simple images.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+import sys
+from docutils import nodes, utils
+from docutils.parsers.rst import directives
+
+
+align_values = ('top', 'middle', 'bottom', 'left', 'center', 'right')
+
+def align(argument):
+    return directives.choice(argument, align_values)
+
+def image(name, arguments, options, content, lineno,
+          content_offset, block_text, state, state_machine):
+    reference = ''.join(arguments[0].split('\n'))
+    if reference.find(' ') != -1:
+        error = state_machine.reporter.error(
+              'Image URI contains whitespace.',
+              nodes.literal_block(block_text, block_text), line=lineno)
+        return [error]
+    options['uri'] = reference
+    image_node = nodes.image(block_text, **options)
+    return [image_node]
+
+image.arguments = (1, 0, 1)
+image.options = {'alt': directives.unchanged,
+                 'height': directives.nonnegative_int,
+                 'width': directives.nonnegative_int,
+                 'scale': directives.nonnegative_int,
+                 'align': align}
+
+def figure(name, arguments, options, content, lineno,
+           content_offset, block_text, state, state_machine):
+    (image_node,) = image(name, arguments, options, content, lineno,
+                         content_offset, block_text, state, state_machine)
+    if isinstance(image_node, nodes.system_message):
+        return [image_node]
+    figure_node = nodes.figure('', image_node)
+    if content:
+        node = nodes.Element()          # anonymous container for parsing
+        state.nested_parse(content, content_offset, node)
+        first_node = node[0]
+        if isinstance(first_node, nodes.paragraph):
+            caption = nodes.caption(first_node.rawsource, '',
+                                    *first_node.children)
+            figure_node += caption
+        elif not (isinstance(first_node, nodes.comment)
+                  and len(first_node) == 0):
+            error = state_machine.reporter.error(
+                  'Figure caption must be a paragraph or empty comment.',
+                  nodes.literal_block(block_text, block_text), line=lineno)
+            return [figure_node, error]
+        if len(node) > 1:
+            figure_node += nodes.legend('', *node[1:])
+    return [figure_node]
+
+figure.arguments = (1, 0, 1)
+figure.options = image.options
+figure.content = 1

lib/python/docutils/parsers/rst/directives/misc.py

+# Authors: David Goodger, Dethe Elza
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:09 $
+# Copyright: This module has been placed in the public domain.
+
+"""Miscellaneous directives."""
+
+__docformat__ = 'reStructuredText'
+
+import sys
+import os.path
+from urllib2 import urlopen, URLError
+from docutils import io, nodes, statemachine, utils
+from docutils.parsers.rst import directives, states
+
+
+def include(name, arguments, options, content, lineno,
+            content_offset, block_text, state, state_machine):
+    """Include a reST file as part of the content of this reST file."""
+    source = state_machine.input_lines.source(
+        lineno - state_machine.input_offset - 1)
+    source_dir = os.path.dirname(os.path.abspath(source))
+    path = ''.join(arguments[0].splitlines())
+    if path.find(' ') != -1:
+        error = state_machine.reporter.error(
+              '"%s" directive path contains whitespace.' % name,
+              nodes.literal_block(block_text, block_text), line=lineno)
+        return [error]
+    path = os.path.normpath(os.path.join(source_dir, path))
+    path = utils.relative_path(None, path)
+    try:
+        include_file = io.FileInput(
+            source_path=path, encoding=state.document.settings.input_encoding)
+    except IOError, error:
+        severe = state_machine.reporter.severe(
+              'Problems with "%s" directive path:\n%s.' % (name, error),
+              nodes.literal_block(block_text, block_text), line=lineno)
+        return [severe]
+    include_text = include_file.read()
+    if options.has_key('literal'):
+        literal_block = nodes.literal_block(include_text, include_text,
+                                            source=path)
+        literal_block.line = 1
+        return literal_block
+    else:
+        include_lines = statemachine.string2lines(include_text,
+                                                  convert_whitespace=1)
+        state_machine.insert_input(include_lines, path)
+        return []
+
+include.arguments = (1, 0, 1)
+include.options = {'literal': directives.flag}
+
+def raw(name, arguments, options, content, lineno,
+        content_offset, block_text, state, state_machine):
+    """
+    Pass through content unchanged
+
+    Content is included in output based on type argument
+
+    Content may be included inline (content section of directive) or
+    imported from a file or url.
+    """
+    attributes = {'format': arguments[0]}
+    if content:
+        if options.has_key('file') or options.has_key('url'):
+            error = state_machine.reporter.error(
+                  '"%s" directive may not both specify an external file and '
+                  'have content.' % name,
+                  nodes.literal_block(block_text, block_text), line=lineno)
+            return [error]
+        text = '\n'.join(content)
+    elif options.has_key('file'):
+        if options.has_key('url'):
+            error = state_machine.reporter.error(
+                  'The "file" and "url" options may not be simultaneously '
+                  'specified for the "%s" directive.' % name,
+                  nodes.literal_block(block_text, block_text), line=lineno)
+            return [error]
+        source_dir = os.path.dirname(
+            os.path.abspath(state.document.current_source))
+        path = os.path.normpath(os.path.join(source_dir, options['file']))
+        path = utils.relative_path(None, path)
+        try:
+            raw_file = open(path)
+        except IOError, error:
+            severe = state_machine.reporter.severe(
+                  'Problems with "%s" directive path:\n%s.' % (name, error),
+                  nodes.literal_block(block_text, block_text), line=lineno)
+            return [severe]
+        text = raw_file.read()
+        raw_file.close()
+        attributes['source'] = path
+    elif options.has_key('url'):
+        try:
+            raw_file = urlopen(options['url'])
+        except (URLError, IOError, OSError), error:
+            severe = state_machine.reporter.severe(
+                  'Problems with "%s" directive URL "%s":\n%s.'
+                  % (name, options['url'], error),
+                  nodes.literal_block(block_text, block_text), line=lineno)
+            return [severe]
+        text = raw_file.read()
+        raw_file.close()        
+        attributes['source'] = options['file']
+    else:
+        error = state_machine.reporter.warning(
+            'The "%s" directive requires content; none supplied.' % (name),
+            nodes.literal_block(block_text, block_text), line=lineno)
+        return [error]
+    raw_node = nodes.raw('', text, **attributes)
+    return [raw_node]
+
+raw.arguments = (1, 0, 1)
+raw.options = {'file': directives.path,
+               'url': directives.path}
+raw.content = 1
+
+def replace(name, arguments, options, content, lineno,
+            content_offset, block_text, state, state_machine):
+    if not isinstance(state, states.SubstitutionDef):
+        error = state_machine.reporter.error(
+            'Invalid context: the "%s" directive can only be used within a '
+            'substitution definition.' % (name),
+            nodes.literal_block(block_text, block_text), line=lineno)
+        return [error]
+    text = '\n'.join(content)
+    element = nodes.Element(text)
+    if text:
+        state.nested_parse(content, content_offset, element)
+        if len(element) != 1 or not isinstance(element[0], nodes.paragraph):
+            messages = []
+            for node in element:
+                if isinstance(node, nodes.system_message):
+                    if node.has_key('backrefs'):
+                        del node['backrefs']
+                    messages.append(node)
+            error = state_machine.reporter.error(
+                'Error in "%s" directive: may contain a single paragraph '
+                'only.' % (name), line=lineno)
+            messages.append(error)
+            return messages
+        else:
+            return element[0].children
+    else:
+        error = state_machine.reporter.error(
+            'The "%s" directive is empty; content required.' % (name),
+            line=lineno)
+        return [error]
+
+replace.content = 1
+
+def directive_test_function(name, arguments, options, content, lineno,
+                            content_offset, block_text, state, state_machine):
+    if content:
+        text = '\n'.join(content)
+        info = state_machine.reporter.info(
+            'Directive processed. Type="%s", arguments=%r, options=%r, '
+            'content:' % (name, arguments, options),
+            nodes.literal_block(text, text), line=lineno)
+    else:
+        info = state_machine.reporter.info(
+            'Directive processed. Type="%s", arguments=%r, options=%r, '
+            'content: None' % (name, arguments, options), line=lineno)
+    return [info]
+
+directive_test_function.arguments = (0, 1, 1)
+directive_test_function.options = {'option': directives.unchanged}
+directive_test_function.content = 1

lib/python/docutils/parsers/rst/directives/parts.py

+# Author: David Goodger, Dmitry Jemerov
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:09 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Directives for document parts.
+"""
+
+__docformat__ = 'reStructuredText'
+
+from docutils import nodes
+from docutils.transforms import parts
+from docutils.parsers.rst import directives
+
+
+backlinks_values = ('top', 'entry', 'none')
+
+def backlinks(arg):
+    value = directives.choice(arg, backlinks_values)
+    if value == 'none':
+        return None
+    else:
+        return value
+
+def contents(name, arguments, options, content, lineno,
+             content_offset, block_text, state, state_machine):
+    """Table of contents."""
+    if arguments:
+        title_text = arguments[0]
+        text_nodes, messages = state.inline_text(title_text, lineno)
+        title = nodes.title(title_text, '', *text_nodes)
+    else:
+        messages = []
+        title = None
+    pending = nodes.pending(parts.Contents, {'title': title}, block_text)
+    pending.details.update(options)
+    state_machine.document.note_pending(pending)
+    return [pending] + messages
+
+contents.arguments = (0, 1, 1)
+contents.options = {'depth': directives.nonnegative_int,
+                    'local': directives.flag,
+                    'backlinks': backlinks}
+
+def sectnum(name, arguments, options, content, lineno,
+            content_offset, block_text, state, state_machine):
+    """Automatic section numbering."""
+    pending = nodes.pending(parts.SectNum)
+    pending.details.update(options)
+    state_machine.document.note_pending(pending)
+    return [pending]
+
+sectnum.options = {'depth': int}

lib/python/docutils/parsers/rst/directives/references.py

+# Author: David Goodger, Dmitry Jemerov
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:09 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Directives for references and targets.
+"""
+
+__docformat__ = 'reStructuredText'
+
+from docutils import nodes
+from docutils.transforms import references
+
+
+def target_notes(name, arguments, options, content, lineno,
+                 content_offset, block_text, state, state_machine):
+    """Target footnote generation."""
+    pending = nodes.pending(references.TargetNotes)
+    state_machine.document.note_pending(pending)
+    nodelist = [pending]
+    return nodelist

lib/python/docutils/parsers/rst/languages/__init__.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:13 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+This package contains modules for language-dependent features of
+reStructuredText.
+"""
+
+__docformat__ = 'reStructuredText'
+
+_languages = {}
+
+def get_language(language_code):
+    if _languages.has_key(language_code):
+        return _languages[language_code]
+    try:
+        module = __import__(language_code, globals(), locals())
+    except ImportError:
+        return None
+    _languages[language_code] = module
+    return module

lib/python/docutils/parsers/rst/languages/de.py

+# Author: Engelbert Gruber
+# Contact: grubert@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:13 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+German-language mappings for language-dependent features of
+reStructuredText.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+directives = {
+      'achtung': 'attention',
+      'vorsicht': 'caution',
+      'gefahr': 'danger',
+      'fehler': 'error',
+      'hinweis': 'hint',
+      'wichtig': 'important',
+      'notiz': 'note',
+      'tip': 'tip',
+      'warnung': 'warning',
+      'topic': 'topic',  # berbegriff
+      'line-block': 'line-block',
+      'parsed-literal': 'parsed-literal',
+      #'questions': 'questions',
+      #'qa': 'questions',
+      #'faq': 'questions',
+      'meta': 'meta',
+      #'imagemap': 'imagemap',
+      'bild': 'image',
+      'abbildung': 'figure',
+      'raw': 'raw',         # unbearbeitet
+      'include': 'include', # einfgen, "fge ein" would be more like a command.
+                            # einfgung would be the noun. 
+      'replace': 'replace', # ersetzen, ersetze
+      'inhalt': 'contents',
+      'sectnum': 'sectnum',
+      'section-numbering': 'sectnum',
+      'target-notes': 'target-notes',
+      #'footnotes': 'footnotes',
+      #'citations': 'citations',
+      'restructuredtext-test-directive': 'restructuredtext-test-directive'}
+"""English name to registered (in directives/__init__.py) directive name
+mapping."""

lib/python/docutils/parsers/rst/languages/en.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:13 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+English-language mappings for language-dependent features of
+reStructuredText.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+directives = {
+      'attention': 'attention',
+      'caution': 'caution',
+      'danger': 'danger',
+      'error': 'error',
+      'hint': 'hint',
+      'important': 'important',
+      'note': 'note',
+      'tip': 'tip',
+      'warning': 'warning',
+      'topic': 'topic',
+      'line-block': 'line-block',
+      'parsed-literal': 'parsed-literal',
+      #'questions': 'questions',
+      #'qa': 'questions',
+      #'faq': 'questions',
+      'meta': 'meta',
+      #'imagemap': 'imagemap',
+      'image': 'image',
+      'figure': 'figure',
+      'include': 'include',
+      'raw': 'raw',
+      'replace': 'replace',
+      'contents': 'contents',
+      'sectnum': 'sectnum',
+      'section-numbering': 'sectnum',
+      'target-notes': 'target-notes',
+      #'footnotes': 'footnotes',
+      #'citations': 'citations',
+      'restructuredtext-test-directive': 'restructuredtext-test-directive'}
+"""English name to registered (in directives/__init__.py) directive name
+mapping."""
+
+roles = {
+    'abbreviation': 'abbreviation',
+    'ab': 'abbreviation',
+    'acronym': 'acronym',
+    'ac': 'acronym',
+    'index': 'index',
+    'i': 'index',
+    'title-reference': 'title-reference',
+    'title': 'title-reference',
+    't': 'title-reference',
+    'pep-reference': 'pep-reference',
+    'pep': 'pep-reference',
+    'rfc-reference': 'rfc-reference',
+    'rfc': 'rfc-reference',
+    'emphasis': 'emphasis',
+    'strong': 'strong',
+    'literal': 'literal',
+    'named-reference': 'named-reference',
+    'anonymous-reference': 'anonymous-reference',
+    'footnote-reference': 'footnote-reference',
+    'citation-reference': 'citation-reference',
+    'substitution-reference': 'substitution-reference',
+    'target': 'target',
+    'uri-reference': 'uri-reference',
+    'uri': 'uri-reference',
+    'url': 'uri-reference',
+    }
+"""Mapping of English role names to canonical role names for interpreted text.
+"""

lib/python/docutils/parsers/rst/languages/fr.py

+# Author: your name here!
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:13 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+French-language mappings for language-dependent features of
+reStructuredText.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+directives = {
+      'attention (translation required)': 'attention',
+      'caution (translation required)': 'caution',
+      'danger (translation required)': 'danger',
+      'error (translation required)': 'error',
+      'hint (translation required)': 'hint',
+      'important (translation required)': 'important',
+      'note (translation required)': 'note',
+      'tip (translation required)': 'tip',
+      'warning (translation required)': 'warning',
+      'topic (translation required)': 'topic',
+      'line-block (translation required)': 'line-block',
+      'parsed-literal (translation required)': 'parsed-literal',
+      #'questions (translation required)': 'questions',
+      #'qa (translation required)': 'questions',
+      #'faq (translation required)': 'questions',
+      'meta (translation required)': 'meta',
+      #'imagemap (translation required)': 'imagemap',
+      'image (translation required)': 'image',
+      'figure (translation required)': 'figure',
+      'include (translation required)': 'include',
+      'raw (translation required)': 'raw',
+      'replace (translation required)': 'replace',
+      'contents (translation required)': 'contents',
+      'sectnum (translation required)': 'sectnum',
+      'section-numbering (translation required)': 'sectnum',
+      'target-notes (translation required)': 'target-notes',
+      #'footnotes (translation required)': 'footnotes',
+      #'citations (translation required)': 'citations',
+      }
+"""French name to registered (in directives/__init__.py) directive name
+mapping."""

lib/python/docutils/parsers/rst/languages/it.py

+# Author: Nicola Larosa
+# Contact: docutils@tekNico.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:13 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Italian-language mappings for language-dependent features of
+reStructuredText.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+directives = {
+      'attenzione': 'attention',
+      'cautela': 'caution',
+      'pericolo': 'danger',
+      'errore': 'error',
+      'suggerimento': 'hint',
+      'importante': 'important',
+      'nota': 'note',
+      'consiglio': 'tip',
+      'avvertenza': 'warning',
+      'argomento': 'topic',
+      'blocco di linee': 'line-block',
+      'parsed-literal': 'parsed-literal',
+      #'questions': 'questions',
+      #'qa': 'questions',
+      #'faq': 'questions',
+      'meta': 'meta',
+      #'imagemap': 'imagemap',
+      'immagine': 'image',
+      'figura': 'figure',
+      'includi': 'include',
+      'grezzo': 'raw',
+      'sostituisci': 'replace',
+      'indice': 'contents',
+      'seznum': 'sectnum',
+      'section-numbering': 'sectnum',
+      'target-notes': 'target-notes',
+      #'footnotes': 'footnotes',
+      #'citations': 'citations',
+      'restructuredtext-test-directive': 'restructuredtext-test-directive'}
+"""English name to registered (in directives/__init__.py) directive name
+mapping."""

lib/python/docutils/parsers/rst/languages/sk.py

+# Author: Miroslav Vasko
+# Contact: zemiak@zoznam.sk
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:13 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Slovak-language mappings for language-dependent features of
+reStructuredText.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+directives = {
+      u'pozor': 'attention',
+      u'opatrne': 'caution',
+      u'nebezpe\xe8enstvo': 'danger',
+      u'chyba': 'error',
+      u'rada': 'hint',
+      u'd\xf4le\x9eit\xe9': 'important',
+      u'pozn\xe1mka': 'note',
+      u'tip': 'tip',
+      u'varovanie': 'warning',
+      u't\xe9ma': 'topic',
+      u'blok-riadkov': 'line-block',
+      u'parsed-literal': 'parsed-literal',
+      #u'questions': 'questions',
+      #u'qa': 'questions',
+      #u'faq': 'questions',
+      u'meta': 'meta',
+      #u'imagemap': 'imagemap',
+      u'obr\xe1zok': 'image',
+      u'tvar': 'figure',
+      u'vlo\x9ei\x9d': 'include',
+      u'raw': 'raw',
+      u'nahradi\x9d': 'replace',
+      u'obsah': 'contents',
+      u'\xe8as\x9d': 'sectnum',
+      u'\xe8as\x9d-\xe8\xedslovanie': 'sectnum',
+      u'cie\xbeov\xe9-pozn\xe1mky': 'target-notes',
+      #u'footnotes': 'footnotes',
+      #u'citations': 'citations',
+      }
+"""Slovak name to registered (in directives/__init__.py) directive name
+mapping."""

lib/python/docutils/parsers/rst/languages/sv.py

+# Author:    Adam Chodorowski
+# Contact:   chodorowski@users.sourceforge.net
+# Revision:  $Revision: 1.2 $
+# Date:      $Date: 2003/02/01 09:26:13 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Swedish language mappings for language-dependent features of reStructuredText.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+directives = {
+      u'observera': 'attention',
+      u'caution (translation required)': 'caution',
+      u'fara': 'danger',
+      u'fel': 'error',
+      u'v\u00e4gledning': 'hint',
+      u'viktigt': 'important',
+      u'notera': 'note',
+      u'tips': 'tip',
+      u'varning': 'warning',
+      u'\u00e4mne': 'topic',
+      'line-block (translation required)': 'line-block',
+      'parsed-literal (translation required)': 'parsed-literal',
+      # u'fr\u00e5gor': 'questions',
+      # NOTE: A bit long, but recommended by http://www.nada.kth.se/dataterm/:
+      # u'fr\u00e5gor-och-svar': 'questions',
+      # u'vanliga-fr\u00e5gor': 'questions',  
+      u'meta': 'meta',
+      # u'bildkarta': 'imagemap',   # FIXME: Translation might be too literal.
+      u'bild': 'image',
+      u'figur': 'figure',
+      'include (translation required)': 'include',
+      u'r\u00e5': 'raw',            # FIXME: Translation might be too literal.
+      'replace (translation required)': 'replace',
+      u'inneh\u00e5ll': 'contents',
+      'sectnum (translation required)': 'sectnum',
+      'section-numbering (translation required)': 'sectnum',
+      'target-notes (translation required)': 'target-notes',
+      # u'fotnoter': 'footnotes',
+      # u'citeringar': 'citations',
+      }
+"""Swedish name to registered (in directives/__init__.py) directive name
+mapping."""

lib/python/docutils/parsers/rst/tableparser.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:07 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+This module defines table parser classes,which parse plaintext-graphic tables
+and produce a well-formed data structure suitable for building a CALS table.
+
+:Classes:
+    - `GridTableParser`: Parse fully-formed tables represented with a grid.
+    - `SimpleTableParser`: Parse simple tables, delimited by top & bottom
+      borders.
+
+:Exception class: `TableMarkupError`
+
+:Function:
+    `update_dict_of_lists()`: Merge two dictionaries containing list values.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+import re
+import sys
+from docutils import DataError
+
+
+class TableMarkupError(DataError): pass
+
+
+class TableParser:
+
+    """
+    Abstract superclass for the common parts of the syntax-specific parsers.
+    """
+
+    head_body_separator_pat = None
+    """Matches the row separator between head rows and body rows."""
+
+    def parse(self, block):
+        """
+        Analyze the text `block` and return a table data structure.
+
+        Given a plaintext-graphic table in `block` (list of lines of text; no
+        whitespace padding), parse the table, construct and return the data
+        necessary to construct a CALS table or equivalent.
+
+        Raise `TableMarkupError` if there is any problem with the markup.
+        """
+        self.setup(block)
+        self.find_head_body_sep()
+        self.parse_table()
+        structure = self.structure_from_cells()
+        return structure
+
+    def find_head_body_sep(self):
+        """Look for a head/body row separator line; store the line index."""
+        for i in range(len(self.block)):
+            line = self.block[i]
+            if self.head_body_separator_pat.match(line):
+                if self.head_body_sep:
+                    raise TableMarkupError(
+                        'Multiple head/body row separators in table (at line '
+                        'offset %s and %s); only one allowed.'
+                        % (self.head_body_sep, i))
+                else:
+                    self.head_body_sep = i
+                    self.block[i] = line.replace('=', '-')
+        if self.head_body_sep == 0 or self.head_body_sep == (len(self.block)
+                                                             - 1):
+            raise TableMarkupError('The head/body row separator may not be '
+                                   'the first or last line of the table.')
+
+
+class GridTableParser(TableParser):
+
+    """
+    Parse a grid table using `parse()`.
+
+    Here's an example of a grid table::
+
+        +------------------------+------------+----------+----------+
+        | Header row, column 1   | Header 2   | Header 3 | Header 4 |
+        +========================+============+==========+==========+
+        | body row 1, column 1   | column 2   | column 3 | column 4 |
+        +------------------------+------------+----------+----------+
+        | body row 2             | Cells may span columns.          |
+        +------------------------+------------+---------------------+
+        | body row 3             | Cells may  | - Table cells       |
+        +------------------------+ span rows. | - contain           |
+        | body row 4             |            | - body elements.    |
+        +------------------------+------------+---------------------+
+
+    Intersections use '+', row separators use '-' (except for one optional
+    head/body row separator, which uses '='), and column separators use '|'.
+
+    Passing the above table to the `parse()` method will result in the
+    following data structure::
+
+        ([24, 12, 10, 10],
+         [[(0, 0, 1, ['Header row, column 1']),
+           (0, 0, 1, ['Header 2']),
+           (0, 0, 1, ['Header 3']),
+           (0, 0, 1, ['Header 4'])]],
+         [[(0, 0, 3, ['body row 1, column 1']),
+           (0, 0, 3, ['column 2']),
+           (0, 0, 3, ['column 3']),
+           (0, 0, 3, ['column 4'])],
+          [(0, 0, 5, ['body row 2']),
+           (0, 2, 5, ['Cells may span columns.']),
+           None,
+           None],
+          [(0, 0, 7, ['body row 3']),
+           (1, 0, 7, ['Cells may', 'span rows.', '']),
+           (1, 1, 7, ['- Table cells', '- contain', '- body elements.']),
+           None],
+          [(0, 0, 9, ['body row 4']), None, None, None]])
+
+    The first item is a list containing column widths (colspecs). The second
+    item is a list of head rows, and the third is a list of body rows. Each
+    row contains a list of cells. Each cell is either None (for a cell unused
+    because of another cell's span), or a tuple. A cell tuple contains four
+    items: the number of extra rows used by the cell in a vertical span
+    (morerows); the number of extra columns used by the cell in a horizontal
+    span (morecols); the line offset of the first line of the cell contents;
+    and the cell contents, a list of lines of text.
+    """
+
+    head_body_separator_pat = re.compile(r'\+=[=+]+=\+ *$')
+
+    def setup(self, block):
+        self.block = list(block)        # make a copy; it may be modified
+        self.bottom = len(block) - 1
+        self.right = len(block[0]) - 1
+        self.head_body_sep = None
+        self.done = [-1] * len(block[0])
+        self.cells = []
+        self.rowseps = {0: [0]}
+        self.colseps = {0: [0]}
+
+    def parse_table(self):
+        """
+        Start with a queue of upper-left corners, containing the upper-left
+        corner of the table itself. Trace out one rectangular cell, remember
+        it, and add its upper-right and lower-left corners to the queue of
+        potential upper-left corners of further cells. Process the queue in
+        top-to-bottom order, keeping track of how much of each text column has
+        been seen.
+
+        We'll end up knowing all the row and column boundaries, cell positions
+        and their dimensions.
+        """
+        corners = [(0, 0)]
+        while corners:
+            top, left = corners.pop(0)
+            if top == self.bottom or left == self.right \
+                  or top <= self.done[left]:
+                continue
+            result = self.scan_cell(top, left)
+            if not result:
+                continue
+            bottom, right, rowseps, colseps = result
+            update_dict_of_lists(self.rowseps, rowseps)
+            update_dict_of_lists(self.colseps, colseps)
+            self.mark_done(top, left, bottom, right)
+            cellblock = self.get_cell_block(top, left, bottom, right)
+            self.cells.append((top, left, bottom, right, cellblock))
+            corners.extend([(top, right), (bottom, left)])
+            corners.sort()
+        if not self.check_parse_complete():
+            raise TableMarkupError('Malformed table; parse incomplete.')
+
+    def mark_done(self, top, left, bottom, right):
+        """For keeping track of how much of each text column has been seen."""
+        before = top - 1
+        after = bottom - 1
+        for col in range(left, right):
+            assert self.done[col] == before
+            self.done[col] = after
+
+    def check_parse_complete(self):
+        """Each text column should have been completely seen."""
+        last = self.bottom - 1
+        for col in range(self.right):
+            if self.done[col] != last:
+                return None
+        return 1
+
+    def get_cell_block(self, top, left, bottom, right):
+        """Given the corners, extract the text of a cell."""
+        cellblock = []
+        margin = right
+        for lineno in range(top + 1, bottom):
+            line = self.block[lineno][left + 1 : right].rstrip()
+            cellblock.append(line)
+            if line:
+                margin = min(margin, len(line) - len(line.lstrip()))
+        if 0 < margin < right:
+            cellblock = [line[margin:] for line in cellblock]
+        return cellblock
+
+    def scan_cell(self, top, left):
+        """Starting at the top-left corner, start tracing out a cell."""
+        assert self.block[top][left] == '+'
+        result = self.scan_right(top, left)
+        return result
+
+    def scan_right(self, top, left):
+        """
+        Look for the top-right corner of the cell, and make note of all column
+        boundaries ('+').
+        """
+        colseps = {}
+        line = self.block[top]
+        for i in range(left + 1, self.right + 1):
+            if line[i] == '+':
+                colseps[i] = [top]
+                result = self.scan_down(top, left, i)
+                if result:
+                    bottom, rowseps, newcolseps = result
+                    update_dict_of_lists(colseps, newcolseps)
+                    return bottom, i, rowseps, colseps
+            elif line[i] != '-':
+                return None
+        return None
+
+    def scan_down(self, top, left, right):
+        """
+        Look for the bottom-right corner of the cell, making note of all row
+        boundaries.
+        """
+        rowseps = {}
+        for i in range(top + 1, self.bottom + 1):
+            if self.block[i][right] == '+':
+                rowseps[i] = [right]
+                result = self.scan_left(top, left, i, right)
+                if result:
+                    newrowseps, colseps = result
+                    update_dict_of_lists(rowseps, newrowseps)
+                    return i, rowseps, colseps
+            elif self.block[i][right] != '|':
+                return None
+        return None
+
+    def scan_left(self, top, left, bottom, right):
+        """
+        Noting column boundaries, look for the bottom-left corner of the cell.
+        It must line up with the starting point.
+        """
+        colseps = {}
+        line = self.block[bottom]
+        for i in range(right - 1, left, -1):
+            if line[i] == '+':
+                colseps[i] = [bottom]
+            elif line[i] != '-':
+                return None
+        if line[left] != '+':
+            return None
+        result = self.scan_up(top, left, bottom, right)
+        if result is not None:
+            rowseps = result
+            return rowseps, colseps
+        return None
+
+    def scan_up(self, top, left, bottom, right):
+        """
+        Noting row boundaries, see if we can return to the starting point.
+        """
+        rowseps = {}
+        for i in range(bottom - 1, top, -1):
+            if self.block[i][left] == '+':
+                rowseps[i] = [left]
+            elif self.block[i][left] != '|':
+                return None
+        return rowseps
+
+    def structure_from_cells(self):
+        """
+        From the data colledted by `scan_cell()`, convert to the final data
+        structure.
+        """
+        rowseps = self.rowseps.keys()   # list of row boundaries
+        rowseps.sort()
+        rowindex = {}
+        for i in range(len(rowseps)):
+            rowindex[rowseps[i]] = i    # row boundary -> row number mapping
+        colseps = self.colseps.keys()   # list of column boundaries
+        colseps.sort()
+        colindex = {}
+        for i in range(len(colseps)):
+            colindex[colseps[i]] = i    # column boundary -> col number map
+        colspecs = [(colseps[i] - colseps[i - 1] - 1)
+                    for i in range(1, len(colseps))] # list of column widths
+        # prepare an empty table with the correct number of rows & columns
+        onerow = [None for i in range(len(colseps) - 1)]
+        rows = [onerow[:] for i in range(len(rowseps) - 1)]
+        # keep track of # of cells remaining; should reduce to zero
+        remaining = (len(rowseps) - 1) * (len(colseps) - 1)
+        for top, left, bottom, right, block in self.cells:
+            rownum = rowindex[top]
+            colnum = colindex[left]
+            assert rows[rownum][colnum] is None, (
+                  'Cell (row %s, column %s) already used.'
+                  % (rownum + 1, colnum + 1))
+            morerows = rowindex[bottom] - rownum - 1
+            morecols = colindex[right] - colnum - 1
+            remaining -= (morerows + 1) * (morecols + 1)
+            # write the cell into the table
+            rows[rownum][colnum] = (morerows, morecols, top + 1, block)
+        assert remaining == 0, 'Unused cells remaining.'
+        if self.head_body_sep:          # separate head rows from body rows
+            numheadrows = rowindex[self.head_body_sep]
+            headrows = rows[:numheadrows]
+            bodyrows = rows[numheadrows:]
+        else:
+            headrows = []
+            bodyrows = rows
+        return (colspecs, headrows, bodyrows)
+
+
+class SimpleTableParser(TableParser):
+
+    """
+    Parse a simple table using `parse()`.
+
+    Here's an example of a simple table::
+
+        =====  =====
+        col 1  col 2
+        =====  =====
+        1      Second column of row 1.
+        2      Second column of row 2.
+               Second line of paragraph.
+        3      - Second column of row 3.
+
+               - Second item in bullet
+                 list (row 3, column 2).
+        4 is a span
+        ------------
+        5
+        =====  =====
+
+    Top and bottom borders use '=', column span underlines use '-', column
+    separation is indicated with spaces.
+
+    Passing the above table to the `parse()` method will result in the
+    following data structure, whose interpretation is the same as for
+    `GridTableParser`::
+
+        ([5, 25],
+         [[(0, 0, 1, ['col 1']),
+           (0, 0, 1, ['col 2'])]],
+         [[(0, 0, 3, ['1']),
+           (0, 0, 3, ['Second column of row 1.'])],
+          [(0, 0, 4, ['2']),
+           (0, 0, 4, ['Second column of row 2.',
+                      'Second line of paragraph.'])],
+          [(0, 0, 6, ['3']),
+           (0, 0, 6, ['- Second column of row 3.',
+                      '',
+                      '- Second item in bullet',
+                      '  list (row 3, column 2).'])],
+          [(0, 1, 10, ['4 is a span'])],
+          [(0, 0, 12, ['5']),
+           (0, 0, 12, [''])]])
+    """
+
+    head_body_separator_pat = re.compile('=[ =]*$')
+    span_pat = re.compile('-[ -]*$')
+
+    def setup(self, block):
+        self.block = list(block)        # make a copy; it will be modified
+        # Convert top & bottom borders to column span underlines:
+        self.block[0] = self.block[0].replace('=', '-')
+        self.block[-1] = self.block[-1].replace('=', '-')
+        self.head_body_sep = None
+        self.columns = []
+        self.border_end = None
+        self.table = []
+        self.done = [-1] * len(block[0])
+        self.rowseps = {0: [0]}
+        self.colseps = {0: [0]}
+
+    def parse_table(self):
+        """
+        First determine the column boundaries from the top border, then
+        process rows.  Each row may consist of multiple lines; accumulate
+        lines until a row is complete.  Call `self.parse_row` to finish the
+        job.
+        """
+        # Top border must fully describe all table columns.
+        self.columns = self.parse_columns(self.block[0], 0)
+        self.border_end = self.columns[-1][1]
+        firststart, firstend = self.columns[0]
+        block = self.block[1:]
+        offset = 0
+        # Container for accumulating text lines until a row is complete:
+        rowlines = []
+        while block:
+            line = block.pop(0)
+            offset += 1
+            if self.span_pat.match(line):
+                # Column span underline or border; row is complete.
+                self.parse_row(rowlines, (line.rstrip(), offset))
+                rowlines = []
+            elif line[firststart:firstend].strip():
+                # First column not blank, therefore it's a new row.
+                if rowlines:
+                    self.parse_row(rowlines)
+                rowlines = [(line.rstrip(), offset)]
+            else:
+                # Accumulate lines of incomplete row.
+                rowlines.append((line.rstrip(), offset))
+
+    def parse_columns(self, line, offset):
+        """
+        Given a column span underline, return a list of (begin, end) pairs.
+        """
+        cols = []
+        end = 0
+        while 1:
+            begin = line.find('-', end)
+            end = line.find(' ', begin)
+            if begin < 0:
+                break
+            if end < 0:
+                end = len(line)
+            cols.append((begin, end))
+        if self.columns:
+            if cols[-1][1] != self.border_end:
+                raise TableMarkupError('Column span incomplete at line '
+                                       'offset %s.' % offset)
+            # Allow for an unbounded rightmost column:
+            cols[-1] = (cols[-1][0], self.columns[-1][1])
+        return cols
+
+    def init_row(self, colspec, offset):
+        i = 0
+        cells = []
+        for start, end in colspec:
+            morecols = 0
+            try:
+                assert start == self.columns[i][0]
+                while end != self.columns[i][1]:
+                    i += 1
+                    morecols += 1
+            except (AssertionError, IndexError):
+                raise TableMarkupError('Column span alignment problem at '
+                                       'line offset %s.' % offset)
+            cells.append((0, morecols, offset, []))
+            i += 1
+        return cells
+
+    def parse_row(self, lines, spanline=None):
+        """
+        Given the text `lines` of a row, parse it and append to `self.table`.
+
+        The row is parsed according to the current column spec (either
+        `spanline` if provided or `self.columns`).  For each column, extract
+        text from each line, and check for text in column margins.  Finally,
+        adjust for insigificant whitespace.
+        """
+        while lines and not lines[-1][0]:
+            lines.pop()                 # Remove blank trailing lines.
+        if lines:
+            offset = lines[0][1]
+        elif spanline:
+            offset = spanline[1]
+        else:
+            # No new row, just blank lines.
+            return
+        if spanline:
+            columns = self.parse_columns(*spanline)
+        else:
+            columns = self.columns[:]
+        row = self.init_row(columns, offset)
+        # "Infinite" value for a dummy last column's beginning, used to
+        # check for text overflow:
+        columns.append((sys.maxint, None))
+        lastcol = len(columns) - 2
+        for i in range(len(columns) - 1):
+            start, end = columns[i]
+            nextstart = columns[i+1][0]
+            block = []
+            margin = sys.maxint
+            for line, offset in lines:
+                if i == lastcol and line[end:].strip():
+                    text = line[start:].rstrip()
+                    columns[lastcol] = (start, start + len(text))
+                    self.adjust_last_column(start + len(text))
+                elif line[end:nextstart].strip():
+                    raise TableMarkupError('Text in column margin at line '
+                                           'offset %s.' % offset)
+                else:
+                    text = line[start:end].rstrip()
+                block.append(text)
+                if text:
+                    margin = min(margin, len(text) - len(text.lstrip()))
+            if 0 < margin < sys.maxint:
+                block = [line[margin:] for line in block]
+            row[i][3].extend(block)
+        self.table.append(row)
+
+    def adjust_last_column(self, new_end):
+        start, end = self.columns[-1]
+        if new_end > end:
+            self.columns[-1] = (start, new_end)
+
+    def structure_from_cells(self):
+        colspecs = [end - start for start, end in self.columns]
+        first_body_row = 0
+        if self.head_body_sep:
+            for i in range(len(self.table)):
+                if self.table[i][0][2] > self.head_body_sep:
+                    first_body_row = i
+                    break
+        return (colspecs, self.table[:first_body_row],
+                self.table[first_body_row:])
+
+
+def update_dict_of_lists(master, newdata):
+    """
+    Extend the list values of `master` with those from `newdata`.
+
+    Both parameters must be dictionaries containing list values.
+    """
+    for key, values in newdata.items():
+        master.setdefault(key, []).extend(values)

lib/python/docutils/readers/__init__.py

+# Authors: David Goodger; Ueli Schlaepfer
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:15 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+This package contains Docutils Reader modules.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+import sys
+from docutils import utils, parsers, Component
+from docutils.transforms import universal
+
+
+class Reader(Component):
+
+    """
+    Abstract base class for docutils Readers.
+
+    Each reader module or package must export a subclass also called 'Reader'.
+
+    The three steps of a Reader's responsibility are defined: `scan()`,
+    `parse()`, and `transform()`. Call `read()` to process a document.
+    """
+
+    component_type = 'reader'
+
+    def __init__(self, parser=None, parser_name='restructuredtext'):
+        """
+        Initialize the Reader instance.
+
+        Several instance attributes are defined with dummy initial values.
+        Subclasses may use these attributes as they wish.
+        """
+
+        self.parser = parser
+        """A `parsers.Parser` instance shared by all doctrees.  May be left
+        unspecified if the document source determines the parser."""
+
+        if parser is None and parser_name:
+            self.set_parser(parser_name)
+
+        self.source = None
+        """`docutils.io` IO object, source of input data."""
+
+        self.input = None
+        """Raw text input; either a single string or, for more complex cases,
+        a collection of strings."""
+
+    def set_parser(self, parser_name):
+        """Set `self.parser` by name."""
+        parser_class = parsers.get_parser_class(parser_name)
+        self.parser = parser_class()
+
+    def read(self, source, parser, settings):
+        self.source = source
+        if not self.parser:
+            self.parser = parser
+        self.settings = settings
+        self.input = self.source.read()
+        self.parse()
+        return self.document
+
+    def parse(self):
+        """Parse `self.input` into a document tree."""
+        self.document = document = self.new_document()
+        self.parser.parse(self.input, document)
+        document.current_source = document.current_line = None
+
+    def new_document(self):
+        """Create and return a new empty document tree (root node)."""
+        document = utils.new_document(self.source.source_path, self.settings)
+        return document
+
+
+_reader_aliases = {}
+
+def get_reader_class(reader_name):
+    """Return the Reader class from the `reader_name` module."""
+    reader_name = reader_name.lower()
+    if _reader_aliases.has_key(reader_name):
+        reader_name = _reader_aliases[reader_name]
+    module = __import__(reader_name, globals(), locals())
+    return module.Reader

lib/python/docutils/readers/pep.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:15 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Python Enhancement Proposal (PEP) Reader.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+import sys
+import os
+import re
+from docutils import nodes
+from docutils.readers import standalone
+from docutils.transforms import peps, references
+from docutils.parsers import rst
+
+
+class Inliner(rst.states.Inliner):
+
+    """
+    Extend `rst.Inliner` to for local PEP references.
+    """
+
+    pep_url = rst.states.Inliner.pep_url_local
+
+
+class Reader(standalone.Reader):
+
+    supported = ('pep',)
+    """Contexts this reader supports."""
+
+    settings_spec = (
+        'PEP Reader Option Defaults',
+        'The --pep-references and --rfc-references options (for the '
+        'reStructuredText parser) are on by default.',
+        ())
+
+    default_transforms = (references.Substitutions,
+                          peps.Headers,
+                          peps.Contents,
+                          references.ChainedTargets,
+                          references.AnonymousHyperlinks,
+                          references.IndirectHyperlinks,
+                          peps.TargetNotes,
+                          references.Footnotes,
+                          references.ExternalTargets,
+                          references.InternalTargets,)
+
+    settings_default_overrides = {'pep_references': 1, 'rfc_references': 1}
+
+    inliner_class = Inliner
+
+    def __init__(self, parser=None, parser_name=None):
+        """`parser` should be ``None``."""
+        if parser is None:
+            parser = rst.Parser(rfc2822=1, inliner=self.inliner_class())
+        standalone.Reader.__init__(self, parser, '')

lib/python/docutils/readers/standalone.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:15 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Standalone file Reader for the reStructuredText markup syntax.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+import sys
+from docutils import readers
+from docutils.transforms import frontmatter, references
+from docutils.parsers.rst import Parser
+
+
+class Reader(readers.Reader):
+
+    supported = ('standalone',)
+    """Contexts this reader supports."""
+
+    document = None
+    """A single document tree."""
+
+    default_transforms = (references.Substitutions,
+                          frontmatter.DocTitle,
+                          frontmatter.DocInfo,
+                          references.ChainedTargets,
+                          references.AnonymousHyperlinks,
+                          references.IndirectHyperlinks,
+                          references.Footnotes,
+                          references.ExternalTargets,
+                          references.InternalTargets,)

lib/python/docutils/roman.py

+"""Convert to and from Roman numerals"""
+
+__author__ = "Mark Pilgrim (f8dy@diveintopython.org)"
+__version__ = "1.4"
+__date__ = "8 August 2001"
+__copyright__ = """Copyright (c) 2001 Mark Pilgrim
+
+This program is part of "Dive Into Python", a free Python tutorial for
+experienced programmers.  Visit http://diveintopython.org/ for the
+latest version.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the Python 2.1.1 license, available at
+http://www.python.org/2.1.1/license.html
+"""
+
+import re
+
+#Define exceptions
+class RomanError(Exception): pass
+class OutOfRangeError(RomanError): pass
+class NotIntegerError(RomanError): pass
+class InvalidRomanNumeralError(RomanError): pass
+
+#Define digit mapping
+romanNumeralMap = (('M',  1000),
+                   ('CM', 900),
+                   ('D',  500),
+                   ('CD', 400),
+                   ('C',  100),
+                   ('XC', 90),
+                   ('L',  50),
+                   ('XL', 40),
+                   ('X',  10),
+                   ('IX', 9),
+                   ('V',  5),
+                   ('IV', 4),
+                   ('I',  1))
+
+def toRoman(n):
+    """convert integer to Roman numeral"""
+    if not (0 < n < 5000):
+        raise OutOfRangeError, "number out of range (must be 1..4999)"
+    if int(n) <> n:
+        raise NotIntegerError, "decimals can not be converted"
+
+    result = ""
+    for numeral, integer in romanNumeralMap:
+        while n >= integer:
+            result += numeral
+            n -= integer
+    return result
+
+#Define pattern to detect valid Roman numerals
+romanNumeralPattern = re.compile('''
+    ^                   # beginning of string
+    M{0,4}              # thousands - 0 to 4 M's
+    (CM|CD|D?C{0,3})    # hundreds - 900 (CM), 400 (CD), 0-300 (0 to 3 C's),
+                        #            or 500-800 (D, followed by 0 to 3 C's)
+    (XC|XL|L?X{0,3})    # tens - 90 (XC), 40 (XL), 0-30 (0 to 3 X's),
+                        #        or 50-80 (L, followed by 0 to 3 X's)
+    (IX|IV|V?I{0,3})    # ones - 9 (IX), 4 (IV), 0-3 (0 to 3 I's),
+                        #        or 5-8 (V, followed by 0 to 3 I's)
+    $                   # end of string
+    ''' ,re.VERBOSE)
+
+def fromRoman(s):
+    """convert Roman numeral to integer"""
+    if not s:
+        raise InvalidRomanNumeralError, 'Input can not be blank'
+    if not romanNumeralPattern.search(s):
+        raise InvalidRomanNumeralError, 'Invalid Roman numeral: %s' % s
+
+    result = 0
+    index = 0
+    for numeral, integer in romanNumeralMap:
+        while s[index:index+len(numeral)] == numeral:
+            result += integer
+            index += len(numeral)
+    return result
+

lib/python/docutils/statemachine.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:00 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+A finite state machine specialized for regular-expression-based text filters,
+this module defines the following classes:
+
+- `StateMachine`, a state machine
+- `State`, a state superclass
+- `StateMachineWS`, a whitespace-sensitive version of `StateMachine`
+- `StateWS`, a state superclass for use with `StateMachineWS`
+- `SearchStateMachine`, uses `re.search()` instead of `re.match()`
+- `SearchStateMachineWS`, uses `re.search()` instead of `re.match()`
+- `ViewList`, extends standard Python lists.
+- `StringList`, string-specific ViewList.
+
+Exception classes:
+
+- `StateMachineError`
+- `UnknownStateError`
+- `DuplicateStateError`
+- `UnknownTransitionError`
+- `DuplicateTransitionError`
+- `TransitionPatternNotFound`
+- `TransitionMethodNotFound`
+- `UnexpectedIndentationError`
+- `TransitionCorrection`: Raised to switch to another transition.
+- `StateCorrection`: Raised to switch to another state & transition.
+
+Functions:
+
+- `string2lines()`: split a multi-line string into a list of one-line strings
+
+
+How To Use This Module
+======================
+(See the individual classes, methods, and attributes for details.)
+
+1. Import it: ``import statemachine`` or ``from statemachine import ...``.
+   You will also need to ``import re``.
+
+2. Derive a subclass of `State` (or `StateWS`) for each state in your state
+   machine::
+
+       class MyState(statemachine.State):
+
+   Within the state's class definition:
+
+   a) Include a pattern for each transition, in `State.patterns`::
+
+          patterns = {'atransition': r'pattern', ...}
+
+   b) Include a list of initial transitions to be set up automatically, in
+      `State.initial_transitions`::
+
+          initial_transitions = ['atransition', ...]
+
+   c) Define a method for each transition, with the same name as the
+      transition pattern::
+
+          def atransition(self, match, context, next_state):
+              # do something
+              result = [...]  # a list
+              return context, next_state, result
+              # context, next_state may be altered
+
+      Transition methods may raise an `EOFError` to cut processing short.
+
+   d) You may wish to override the `State.bof()` and/or `State.eof()` implicit
+      transition methods, which handle the beginning- and end-of-file.
+
+   e) In order to handle nested processing, you may wish to override the
+      attributes `State.nested_sm` and/or `State.nested_sm_kwargs`.
+
+      If you are using `StateWS` as a base class, in order to handle nested
+      indented blocks, you may wish to:
+
+      - override the attributes `StateWS.indent_sm`,
+        `StateWS.indent_sm_kwargs`, `StateWS.known_indent_sm`, and/or
+        `StateWS.known_indent_sm_kwargs`;
+      - override the `StateWS.blank()` method; and/or
+      - override or extend the `StateWS.indent()`, `StateWS.known_indent()`,
+        and/or `StateWS.firstknown_indent()` methods.
+
+3. Create a state machine object::
+
+       sm = StateMachine(state_classes=[MyState, ...],
+                         initial_state='MyState')
+
+4. Obtain the input text, which needs to be converted into a tab-free list of
+   one-line strings. For example, to read text from a file called
+   'inputfile'::
+
+       input_string = open('inputfile').read()
+       input_lines = statemachine.string2lines(input_string)
+
+5. Run the state machine on the input text and collect the results, a list::
+
+       results = sm.run(input_lines)
+
+6. Remove any lingering circular references::
+
+       sm.unlink()
+"""
+
+__docformat__ = 'restructuredtext'
+
+import sys
+import re
+from types import SliceType as _SliceType
+
+
+class StateMachine:
+
+    """
+    A finite state machine for text filters using regular expressions.
+
+    The input is provided in the form of a list of one-line strings (no
+    newlines). States are subclasses of the `State` class. Transitions consist
+    of regular expression patterns and transition methods, and are defined in
+    each state.
+
+    The state machine is started with the `run()` method, which returns the
+    results of processing in a list.
+    """
+
+    def __init__(self, state_classes, initial_state, debug=0):
+        """
+        Initialize a `StateMachine` object; add state objects.
+
+        Parameters:
+
+        - `state_classes`: a list of `State` (sub)classes.
+        - `initial_state`: a string, the class name of the initial state.
+        - `debug`: a boolean; produce verbose output if true (nonzero).
+        """
+
+        self.input_lines = None
+        """`StringList` of input lines (without newlines).
+        Filled by `self.run()`."""
+
+        self.input_offset = 0
+        """Offset of `self.input_lines` from the beginning of the file."""
+
+        self.line = None
+        """Current input line."""
+
+        self.line_offset = -1
+        """Current input line offset from beginning of `self.input_lines`."""
+
+        self.debug = debug
+        """Debugging mode on/off."""
+
+        self.initial_state = initial_state
+        """The name of the initial state (key to `self.states`)."""
+
+        self.current_state = initial_state
+        """The name of the current state (key to `self.states`)."""
+
+        self.states = {}
+        """Mapping of {state_name: State_object}."""
+
+        self.add_states(state_classes)
+
+        self.observers = []
+        """List of bound methods or functions to call whenever the current
+        line changes.  Observers are called with one argument, ``self``.
+        Cleared at the end of `run()`."""
+
+    def unlink(self):
+        """Remove circular references to objects no longer required."""
+        for state in self.states.values():
+            state.unlink()
+        self.states = None
+
+    def run(self, input_lines, input_offset=0, context=None,
+            input_source=None):
+        """
+        Run the state machine on `input_lines`. Return results (a list).
+
+        Reset `self.line_offset` and `self.current_state`. Run the
+        beginning-of-file transition. Input one line at a time and check for a
+        matching transition. If a match is found, call the transition method
+        and possibly change the state. Store the context returned by the
+        transition method to be passed on to the next transition matched.
+        Accumulate the results returned by the transition methods in a list.
+        Run the end-of-file transition. Finally, return the accumulated
+        results.
+
+        Parameters:
+
+        - `input_lines`: a list of strings without newlines, or `StringList`.
+        - `input_offset`: the line offset of `input_lines` from the beginning
+          of the file.
+        - `context`: application-specific storage.
+        - `input_source`: name or path of source of `input_lines`.
+        """
+        self.runtime_init()
+        if isinstance(input_lines, StringList):
+            self.input_lines = input_lines
+        else:
+            self.input_lines = StringList(input_lines, source=input_source)
+        self.input_offset = input_offset
+        self.line_offset = -1
+        self.current_state = self.initial_state
+        if self.debug:
+            print >>sys.stderr, (
+                '\nStateMachine.run: input_lines (line_offset=%s):\n| %s'
+                % (self.line_offset, '\n| '.join(self.input_lines)))
+        transitions = None
+        results = []
+        state = self.get_state()
+        try:
+            if self.debug:
+                print >>sys.stderr, ('\nStateMachine.run: bof transition')
+            context, result = state.bof(context)
+            results.extend(result)
+            while 1:
+                try:
+                    try:
+                        self.next_line()
+                        if self.debug:
+                            source, offset = self.input_lines.info(
+                                self.line_offset)
+                            print >>sys.stderr, (
+                                '\nStateMachine.run: line (source=%r, '
+                                'offset=%r):\n| %s'
+                                % (source, offset, self.line))
+                        context, next_state, result = self.check_line(
+                            context, state, transitions)
+                    except EOFError:
+                        if self.debug:
+                            print >>sys.stderr, (
+                                '\nStateMachine.run: %s.eof transition'
+                                % state.__class__.__name__)
+                        result = state.eof(context)
+                        results.extend(result)
+                        break
+                    else:
+                        results.extend(result)
+                except TransitionCorrection, exception:
+                    self.previous_line() # back up for another try
+                    transitions = (exception.args[0],)
+                    if self.debug:
+                        print >>sys.stderr, (
+                              '\nStateMachine.run: TransitionCorrection to '
+                              'state "%s", transition %s.'
+                              % (state.__class__.__name__, transitions[0]))
+                    continue
+                except StateCorrection, exception:
+                    self.previous_line() # back up for another try
+                    next_state = exception.args[0]
+                    if len(exception.args) == 1:
+                        transitions = None
+                    else:
+                        transitions = (exception.args[1],)
+                    if self.debug:
+                        print >>sys.stderr, (
+                              '\nStateMachine.run: StateCorrection to state '
+                              '"%s", transition %s.'
+                              % (next_state, transitions[0]))
+                else:
+                    transitions = None
+                state = self.get_state(next_state)
+        except:
+            self.error()
+            raise
+        self.observers = []
+        return results
+
+    def get_state(self, next_state=None):
+        """
+        Return current state object; set it first if `next_state` given.
+
+        Parameter `next_state`: a string, the name of the next state.
+
+        Exception: `UnknownStateError` raised if `next_state` unknown.
+        """
+        if next_state:
+            if self.debug and next_state != self.current_state:
+                print >>sys.stderr, \
+                      ('\nStateMachine.get_state: Changing state from '
+                       '"%s" to "%s" (input line %s).'
+                       % (self.current_state, next_state,
+                          self.abs_line_number()))
+            self.current_state = next_state
+        try:
+            return self.states[self.current_state]
+        except KeyError:
+            raise UnknownStateError(self.current_state)
+
+    def next_line(self, n=1):
+        """Load `self.line` with the `n`'th next line and return it."""
+        try:
+            try:
+                self.line_offset += n
+                self.line = self.input_lines[self.line_offset]
+            except IndexError:
+                self.line = None
+                raise EOFError
+            return self.line
+        finally:
+            self.notify_observers()
+
+    def is_next_line_blank(self):
+        """Return 1 if the next line is blank or non-existant."""
+        try:
+            return not self.input_lines[self.line_offset + 1].strip()
+        except IndexError:
+            return 1
+
+    def at_eof(self):
+        """Return 1 if the input is at or past end-of-file."""
+        return self.line_offset >= len(self.input_lines) - 1
+
+    def at_bof(self):
+        """Return 1 if the input is at or before beginning-of-file."""
+        return self.line_offset <= 0
+
+    def previous_line(self, n=1):
+        """Load `self.line` with the `n`'th previous line and return it."""
+        self.line_offset -= n
+        if self.line_offset < 0:
+            self.line = None
+        else:
+            self.line = self.input_lines[self.line_offset]
+        self.notify_observers()
+        return self.line
+
+    def goto_line(self, line_offset):
+        """Jump to absolute line offset `line_offset`, load and return it."""
+        try:
+            try:
+                self.line_offset = line_offset - self.input_offset
+                self.line = self.input_lines[self.line_offset]
+            except IndexError:
+                self.line = None
+                raise EOFError
+            return self.line
+        finally:
+            self.notify_observers()
+
+    def abs_line_offset(self):
+        """Return line offset of current line, from beginning of file."""
+        return self.line_offset + self.input_offset
+
+    def abs_line_number(self):
+        """Return line number of current line (counting from 1)."""
+        return self.line_offset + self.input_offset + 1
+
+    def insert_input(self, input_lines, source):
+        self.input_lines.insert(self.line_offset + 1, '',
+                                source='internal padding')
+        self.input_lines.insert(self.line_offset + 1, '',
+                                source='internal padding')
+        self.input_lines.insert(self.line_offset + 2,
+                                StringList(input_lines, source))
+
+    def get_text_block(self, flush_left=0):
+        """
+        Return a contiguous block of text.
+
+        If `flush_left` is true, raise `UnexpectedIndentationError` if an
+        indented line is encountered before the text block ends (with a blank
+        line).
+        """
+        try:
+            block = self.input_lines.get_text_block(self.line_offset,
+                                                    flush_left)
+            self.next_line(len(block) - 1)
+            return block
+        except UnexpectedIndentationError, error:
+            block, source, lineno = error
+            self.next_line(len(block) - 1) # advance to last line of block
+            raise
+
+    def check_line(self, context, state, transitions=None):
+        """
+        Examine one line of input for a transition match & execute its method.
+
+        Parameters:
+
+        - `context`: application-dependent storage.
+        - `state`: a `State` object, the current state.
+        - `transitions`: an optional ordered list of transition names to try,
+          instead of ``state.transition_order``.
+
+        Return the values returned by the transition method:
+
+        - context: possibly modified from the parameter `context`;
+        - next state name (`State` subclass name);
+        - the result output of the transition, a list.
+
+        When there is no match, ``state.no_match()`` is called and its return
+        value is returned.
+        """
+        if transitions is None:
+            transitions =  state.transition_order
+        state_correction = None
+        if self.debug:
+            print >>sys.stderr, (
+                  '\nStateMachine.check_line: state="%s", transitions=%r.'
+                  % (state.__class__.__name__, transitions))
+        for name in transitions:
+            pattern, method, next_state = state.transitions[name]
+            match = self.match(pattern)
+            if match:
+                if self.debug:
+                    print >>sys.stderr, (
+                          '\nStateMachine.check_line: Matched transition '
+                          '"%s" in state "%s".'
+                          % (name, state.__class__.__name__))
+                return method(match, context, next_state)
+        else:
+            if self.debug:
+                print >>sys.stderr, (
+                      '\nStateMachine.check_line: No match in state "%s".'
+                      % state.__class__.__name__)
+            return state.no_match(context, transitions)
+
+    def match(self, pattern):
+        """
+        Return the result of a regular expression match.
+
+        Parameter `pattern`: an `re` compiled regular expression.
+        """
+        return pattern.match(self.line)
+
+    def add_state(self, state_class):
+        """
+        Initialize & add a `state_class` (`State` subclass) object.
+
+        Exception: `DuplicateStateError` raised if `state_class` was already
+        added.
+        """
+        statename = state_class.__name__
+        if self.states.has_key(statename):
+            raise DuplicateStateError(statename)
+        self.states[statename] = state_class(self, self.debug)
+
+    def add_states(self, state_classes):
+        """
+        Add `state_classes` (a list of `State` subclasses).
+        """
+        for state_class in state_classes:
+            self.add_state(state_class)
+
+    def runtime_init(self):
+        """
+        Initialize `self.states`.
+        """
+        for state in self.states.values():
+            state.runtime_init()
+
+    def error(self):
+        """Report error details."""
+        type, value, module, line, function = _exception_data()
+        print >>sys.stderr, '%s: %s' % (type, value)
+        print >>sys.stderr, 'input line %s' % (self.abs_line_number())
+        print >>sys.stderr, ('module %s, line %s, function %s'
+                             % (module, line, function))
+
+    def attach_observer(self, observer):
+        """
+        The `observer` parameter is a function or bound method which takes two
+        arguments, the source and offset of the current line.
+        """
+        self.observers.append(observer)
+
+    def detach_observer(self, observer):
+        self.observers.remove(observer)
+
+    def notify_observers(self):
+        for observer in self.observers:
+            try:
+                info = self.input_lines.info(self.line_offset)
+            except IndexError:
+                info = (None, None)
+            observer(*info)
+
+
+class State:
+
+    """
+    State superclass. Contains a list of transitions, and transition methods.
+
+    Transition methods all have the same signature. They take 3 parameters:
+
+    - An `re` match object. ``match.string`` contains the matched input line,
+      ``match.start()`` gives the start index of the match, and
+      ``match.end()`` gives the end index.
+    - A context object, whose meaning is application-defined (initial value
+      ``None``). It can be used to store any information required by the state
+      machine, and the retured context is passed on to the next transition
+      method unchanged.
+    - The name of the next state, a string, taken from the transitions list;
+      normally it is returned unchanged, but it may be altered by the
+      transition method if necessary.
+
+    Transition methods all return a 3-tuple:
+
+    - A context object, as (potentially) modified by the transition method.
+    - The next state name (a return value of ``None`` means no state change).
+    - The processing result, a list, which is accumulated by the state
+      machine.
+
+    Transition methods may raise an `EOFError` to cut processing short.
+
+    There are two implicit transitions, and corresponding transition methods
+    are defined: `bof()` handles the beginning-of-file, and `eof()` handles
+    the end-of-file. These methods have non-standard signatures and return
+    values. `bof()` returns the initial context and results, and may be used
+    to return a header string, or do any other processing needed. `eof()`
+    should handle any remaining context and wrap things up; it returns the
+    final processing result.
+
+    Typical applications need only subclass `State` (or a subclass), set the
+    `patterns` and `initial_transitions` class attributes, and provide
+    corresponding transition methods. The default object initialization will
+    take care of constructing the list of transitions.
+    """
+
+    patterns = None
+    """
+    {Name: pattern} mapping, used by `make_transition()`. Each pattern may
+    be a string or a compiled `re` pattern. Override in subclasses.
+    """
+
+    initial_transitions = None
+    """
+    A list of transitions to initialize when a `State` is instantiated.
+    Each entry is either a transition name string, or a (transition name, next
+    state name) pair. See `make_transitions()`. Override in subclasses.
+    """
+
+    nested_sm = None
+    """
+    The `StateMachine` class for handling nested processing.
+
+    If left as ``None``, `nested_sm` defaults to the class of the state's
+    controlling state machine. Override it in subclasses to avoid the default.
+    """
+
+    nested_sm_kwargs = None
+    """
+    Keyword arguments dictionary, passed to the `nested_sm` constructor.
+
+    Two keys must have entries in the dictionary:
+
+    - Key 'state_classes' must be set to a list of `State` classes.
+    - Key 'initial_state' must be set to the name of the initial state class.
+
+    If `nested_sm_kwargs` is left as ``None``, 'state_classes' defaults to the
+    class of the current state, and 'initial_state' defaults to the name of
+    the class of the current state. Override in subclasses to avoid the
+    defaults.
+    """
+
+    def __init__(self, state_machine, debug=0):
+        """
+        Initialize a `State` object; make & add initial transitions.
+
+        Parameters:
+
+        - `statemachine`: the controlling `StateMachine` object.
+        - `debug`: a boolean; produce verbose output if true (nonzero).
+        """
+
+        self.transition_order = []
+        """A list of transition names in search order."""
+
+        self.transitions = {}
+        """
+        A mapping of transition names to 3-tuples containing
+        (compiled_pattern, transition_method, next_state_name). Initialized as
+        an instance attribute dynamically (instead of as a class attribute)
+        because it may make forward references to patterns and methods in this
+        or other classes.
+        """
+
+        self.add_initial_transitions()
+
+        self.state_machine = state_machine
+        """A reference to the controlling `StateMachine` object."""
+
+        self.debug = debug
+        """Debugging mode on/off."""
+
+        if self.nested_sm is None:
+            self.nested_sm = self.state_machine.__class__
+        if self.nested_sm_kwargs is None:
+            self.nested_sm_kwargs = {'state_classes': [self.__class__],
+                                     'initial_state': self.__class__.__name__}
+
+    def runtime_init(self):
+        """
+        Initialize this `State` before running the state machine; called from
+        `self.state_machine.run()`.
+        """
+        pass
+
+    def unlink(self):
+        """Remove circular references to objects no longer required."""
+        self.state_machine = None
+
+    def add_initial_transitions(self):
+        """Make and add transitions listed in `self.initial_transitions`."""
+        if self.initial_transitions:
+            names, transitions = self.make_transitions(
+                  self.initial_transitions)
+            self.add_transitions(names, transitions)
+
+    def add_transitions(self, names, transitions):
+        """
+        Add a list of transitions to the start of the transition list.
+
+        Parameters:
+
+        - `names`: a list of transition names.
+        - `transitions`: a mapping of names to transition tuples.
+
+        Exceptions: `DuplicateTransitionError`, `UnknownTransitionError`.
+        """
+        for name in names:
+            if self.transitions.has_key(name):
+                raise DuplicateTransitionError(name)
+            if not transitions.has_key(name):
+                raise UnknownTransitionError(name)
+        self.transition_order[:0] = names
+        self.transitions.update(transitions)
+
+    def add_transition(self, name, transition):
+        """
+        Add a transition to the start of the transition list.
+
+        Parameter `transition`: a ready-made transition 3-tuple.
+
+        Exception: `DuplicateTransitionError`.
+        """
+        if self.transitions.has_key(name):
+            raise DuplicateTransitionError(name)
+        self.transition_order[:0] = [name]
+        self.transitions[name] = transition
+
+    def remove_transition(self, name):
+        """
+        Remove a transition by `name`.
+
+        Exception: `UnknownTransitionError`.
+        """
+        try:
+            del self.transitions[name]
+            self.transition_order.remove(name)
+        except:
+            raise UnknownTransitionError(name)
+
+    def make_transition(self, name, next_state=None):
+        """
+        Make & return a transition tuple based on `name`.
+
+        This is a convenience function to simplify transition creation.
+
+        Parameters:
+
+        - `name`: a string, the name of the transition pattern & method. This
+          `State` object must have a method called '`name`', and a dictionary
+          `self.patterns` containing a key '`name`'.
+        - `next_state`: a string, the name of the next `State` object for this
+          transition. A value of ``None`` (or absent) implies no state change
+          (i.e., continue with the same state).
+
+        Exceptions: `TransitionPatternNotFound`, `TransitionMethodNotFound`.
+        """
+        if next_state is None:
+            next_state = self.__class__.__name__
+        try:
+            pattern = self.patterns[name]
+            if not hasattr(pattern, 'match'):
+                pattern = re.compile(pattern)
+        except KeyError:
+            raise TransitionPatternNotFound(
+                  '%s.patterns[%r]' % (self.__class__.__name__, name))
+        try:
+            method = getattr(self, name)
+        except AttributeError:
+            raise TransitionMethodNotFound(
+                  '%s.%s' % (self.__class__.__name__, name))
+        return (pattern, method, next_state)
+
+    def make_transitions(self, name_list):
+        """
+        Return a list of transition names and a transition mapping.
+
+        Parameter `name_list`: a list, where each entry is either a transition
+        name string, or a 1- or 2-tuple (transition name, optional next state
+        name).
+        """
+        stringtype = type('')
+        names = []
+        transitions = {}
+        for namestate in name_list:
+            if type(namestate) is stringtype:
+                transitions[namestate] = self.make_transition(namestate)
+                names.append(namestate)
+            else:
+                transitions[namestate[0]] = self.make_transition(*namestate)
+                names.append(namestate[0])
+        return names, transitions
+
+    def no_match(self, context, transitions):
+        """
+        Called when there is no match from `StateMachine.check_line()`.
+
+        Return the same values returned by transition methods:
+
+        - context: unchanged;
+        - next state name: ``None``;
+        - empty result list.
+
+        Override in subclasses to catch this event.
+        """
+        return context, None, []
+
+    def bof(self, context):
+        """
+        Handle beginning-of-file. Return unchanged `context`, empty result.
+
+        Override in subclasses.
+
+        Parameter `context`: application-defined storage.
+        """
+        return context, []
+
+    def eof(self, context):
+        """
+        Handle end-of-file. Return empty result.
+
+        Override in subclasses.
+
+        Parameter `context`: application-defined storage.
+        """
+        return []
+
+    def nop(self, match, context, next_state):
+        """
+        A "do nothing" transition method.
+
+        Return unchanged `context` & `next_state`, empty result. Useful for
+        simple state changes (actionless transitions).
+        """
+        return context, next_state, []
+
+
+class StateMachineWS(StateMachine):
+
+    """
+    `StateMachine` subclass specialized for whitespace recognition.
+
+    There are three methods provided for extracting indented text blocks:
+    
+    - `get_indented()`: use when the indent is unknown.
+    - `get_known_indented()`: use when the indent is known for all lines.
+    - `get_first_known_indented()`: use when only the first line's indent is
+      known.
+    """
+
+    def get_indented(self, until_blank=0, strip_indent=1):
+        """
+        Return a block of indented lines of text, and info.
+
+        Extract an indented block where the indent is unknown for all lines.
+
+        :Parameters:
+            - `until_blank`: Stop collecting at the first blank line if true
+              (1).
+            - `strip_indent`: Strip common leading indent if true (1,
+              default).
+
+        :Return:
+            - the indented block (a list of lines of text),
+            - its indent,
+            - its first line offset from BOF, and
+            - whether or not it finished with a blank line.
+        """
+        offset = self.abs_line_offset()
+        indented, indent, blank_finish = self.input_lines.get_indented(
+              self.line_offset, until_blank, strip_indent)
+        if indented:
+            self.next_line(len(indented) - 1) # advance to last indented line
+        while indented and not indented[0].strip():
+            indented.trim_start()
+            offset += 1
+        return indented, indent, offset, blank_finish
+
+    def get_known_indented(self, indent, until_blank=0, strip_indent=1):
+        """
+        Return an indented block and info.
+
+        Extract an indented block where the indent is known for all lines.
+        Starting with the current line, extract the entire text block with at
+        least `indent` indentation (which must be whitespace, except for the
+        first line).
+
+        :Parameters:
+            - `indent`: The number of indent columns/characters.
+            - `until_blank`: Stop collecting at the first blank line if true
+              (1).
+            - `strip_indent`: Strip `indent` characters of indentation if true
+              (1, default).
+
+        :Return:
+            - the indented block,
+            - its first line offset from BOF, and
+            - whether or not it finished with a blank line.
+        """
+        offset = self.abs_line_offset()
+        indented, indent, blank_finish = self.input_lines.get_indented(
+              self.line_offset, until_blank, strip_indent,
+              block_indent=indent)
+        self.next_line(len(indented) - 1) # advance to last indented line
+        while indented and not indented[0].strip():
+            indented.trim_start()
+            offset += 1
+        return indented, offset, blank_finish
+
+    def get_first_known_indented(self, indent, until_blank=0, strip_indent=1,
+                                 strip_top=1):
+        """
+        Return an indented block and info.
+
+        Extract an indented block where the indent is known for the first line
+        and unknown for all other lines.
+
+        :Parameters:
+            - `indent`: The first line's indent (# of columns/characters).
+            - `until_blank`: Stop collecting at the first blank line if true
+              (1).
+            - `strip_indent`: Strip `indent` characters of indentation if true
+              (1, default).
+            - `strip_top`: Strip blank lines from the beginning of the block.
+
+        :Return:
+            - the indented block,
+            - its indent,
+            - its first line offset from BOF, and
+            - whether or not it finished with a blank line.
+        """
+        offset = self.abs_line_offset()
+        indented, indent, blank_finish = self.input_lines.get_indented(
+              self.line_offset, until_blank, strip_indent,
+              first_indent=indent)
+        self.next_line(len(indented) - 1) # advance to last indented line
+        if strip_top:
+            while indented and not indented[0].strip():
+                indented.trim_start()
+                offset += 1
+        return indented, indent, offset, blank_finish
+
+
+class StateWS(State):
+
+    """
+    State superclass specialized for whitespace (blank lines & indents).
+
+    Use this class with `StateMachineWS`.  The transitions 'blank' (for blank
+    lines) and 'indent' (for indented text blocks) are added automatically,
+    before any other transitions.  The transition method `blank()` handles
+    blank lines and `indent()` handles nested indented blocks.  Indented
+    blocks trigger a new state machine to be created by `indent()` and run.
+    The class of the state machine to be created is in `indent_sm`, and the
+    constructor keyword arguments are in the dictionary `indent_sm_kwargs`.
+
+    The methods `known_indent()` and `firstknown_indent()` are provided for
+    indented blocks where the indent (all lines' and first line's only,
+    respectively) is known to the transition method, along with the attributes
+    `known_indent_sm` and `known_indent_sm_kwargs`.  Neither transition method
+    is triggered automatically.
+    """
+
+    indent_sm = None
+    """
+    The `StateMachine` class handling indented text blocks.
+
+    If left as ``None``, `indent_sm` defaults to the value of
+    `State.nested_sm`.  Override it in subclasses to avoid the default.
+    """
+
+    indent_sm_kwargs = None
+    """
+    Keyword arguments dictionary, passed to the `indent_sm` constructor.
+
+    If left as ``None``, `indent_sm_kwargs` defaults to the value of
+    `State.nested_sm_kwargs`. Override it in subclasses to avoid the default.
+    """
+
+    known_indent_sm = None
+    """
+    The `StateMachine` class handling known-indented text blocks.
+
+    If left as ``None``, `known_indent_sm` defaults to the value of
+    `indent_sm`.  Override it in subclasses to avoid the default.
+    """
+
+    known_indent_sm_kwargs = None
+    """
+    Keyword arguments dictionary, passed to the `known_indent_sm` constructor.
+
+    If left as ``None``, `known_indent_sm_kwargs` defaults to the value of
+    `indent_sm_kwargs`. Override it in subclasses to avoid the default.
+    """
+
+    ws_patterns = {'blank': ' *$',
+                   'indent': ' +'}
+    """Patterns for default whitespace transitions.  May be overridden in
+    subclasses."""
+
+    ws_initial_transitions = ('blank', 'indent')
+    """Default initial whitespace transitions, added before those listed in
+    `State.initial_transitions`.  May be overridden in subclasses."""
+
+    def __init__(self, state_machine, debug=0):
+        """
+        Initialize a `StateSM` object; extends `State.__init__()`.
+
+        Check for indent state machine attributes, set defaults if not set.
+        """
+        State.__init__(self, state_machine, debug)
+        if self.indent_sm is None:
+            self.indent_sm = self.nested_sm
+        if self.indent_sm_kwargs is None:
+            self.indent_sm_kwargs = self.nested_sm_kwargs
+        if self.known_indent_sm is None:
+            self.known_indent_sm = self.indent_sm
+        if self.known_indent_sm_kwargs is None:
+            self.known_indent_sm_kwargs = self.indent_sm_kwargs
+
+    def add_initial_transitions(self):
+        """
+        Add whitespace-specific transitions before those defined in subclass.
+
+        Extends `State.add_initial_transitions()`.
+        """
+        State.add_initial_transitions(self)
+        if self.patterns is None:
+            self.patterns = {}
+        self.patterns.update(self.ws_patterns)
+        names, transitions = self.make_transitions(
+            self.ws_initial_transitions)
+        self.add_transitions(names, transitions)
+
+    def blank(self, match, context, next_state):
+        """Handle blank lines. Does nothing. Override in subclasses."""
+        return self.nop(match, context, next_state)
+
+    def indent(self, match, context, next_state):
+        """
+        Handle an indented text block. Extend or override in subclasses.
+
+        Recursively run the registered state machine for indented blocks
+        (`self.indent_sm`).
+        """
+        indented, indent, line_offset, blank_finish = \
+              self.state_machine.get_indented()
+        sm = self.indent_sm(debug=self.debug, **self.indent_sm_kwargs)
+        results = sm.run(indented, input_offset=line_offset)
+        return context, next_state, results
+
+    def known_indent(self, match, context, next_state):
+        """
+        Handle a known-indent text block. Extend or override in subclasses.
+
+        Recursively run the registered state machine for known-indent indented
+        blocks (`self.known_indent_sm`). The indent is the length of the
+        match, ``match.end()``.
+        """
+        indented, line_offset, blank_finish = \
+              self.state_machine.get_known_indented(match.end())
+        sm = self.known_indent_sm(debug=self.debug,
+                                 **self.known_indent_sm_kwargs)
+        results = sm.run(indented, input_offset=line_offset)
+        return context, next_state, results
+
+    def first_known_indent(self, match, context, next_state):
+        """
+        Handle an indented text block (first line's indent known).
+
+        Extend or override in subclasses.
+
+        Recursively run the registered state machine for known-indent indented
+        blocks (`self.known_indent_sm`). The indent is the length of the
+        match, ``match.end()``.
+        """
+        indented, line_offset, blank_finish = \
+              self.state_machine.get_first_known_indented(match.end())
+        sm = self.known_indent_sm(debug=self.debug,
+                                 **self.known_indent_sm_kwargs)
+        results = sm.run(indented, input_offset=line_offset)
+        return context, next_state, results
+
+
+class _SearchOverride:
+
+    """
+    Mix-in class to override `StateMachine` regular expression behavior.
+
+    Changes regular expression matching, from the default `re.match()`
+    (succeeds only if the pattern matches at the start of `self.line`) to
+    `re.search()` (succeeds if the pattern matches anywhere in `self.line`).
+    When subclassing a `StateMachine`, list this class **first** in the
+    inheritance list of the class definition.
+    """
+
+    def match(self, pattern):
+        """
+        Return the result of a regular expression search.
+
+        Overrides `StateMachine.match()`.
+
+        Parameter `pattern`: `re` compiled regular expression.
+        """
+        return pattern.search(self.line)
+
+
+class SearchStateMachine(_SearchOverride, StateMachine):
+    """`StateMachine` which uses `re.search()` instead of `re.match()`."""
+    pass
+
+
+class SearchStateMachineWS(_SearchOverride, StateMachineWS):
+    """`StateMachineWS` which uses `re.search()` instead of `re.match()`."""
+    pass
+
+
+class ViewList:
+
+    """
+    List with extended functionality: slices of ViewList objects are child
+    lists, linked to their parents. Changes made to a child list also affect
+    the parent list.  A child list is effectively a "view" (in the SQL sense)
+    of the parent list.  Changes to parent lists, however, do *not* affect
+    active child lists.  If a parent list is changed, any active child lists
+    should be recreated.
+
+    The start and end of the slice can be trimmed using the `trim_start()` and
+    `trim_end()` methods, without affecting the parent list.  The link between
+    child and parent lists can be broken by calling `disconnect()` on the
+    child list.
+
+    Also, ViewList objects keep track of the source & offset of each item. 
+    This information is accessible via the `source()`, `offset()`, and
+    `info()` methods.
+    """
+
+    def __init__(self, initlist=None, source=None, items=None,
+                 parent=None, parent_offset=None):
+        self.data = []
+        """The actual list of data, flattened from various sources."""
+
+        self.items = []
+        """A list of (source, offset) pairs, same length as `self.data`: the
+        source of each line and the offset of each line from the beginning of
+        its source."""
+
+        self.parent = parent
+        """The parent list."""
+
+        self.parent_offset = parent_offset
+        """Offset of this list from the beginning of the parent list."""
+
+        if isinstance(initlist, ViewList):
+            self.data = initlist.data[:]
+            self.items = initlist.items[:]
+        elif initlist is not None:
+            self.data = list(initlist)
+            if items:
+                self.items = items
+            else:
+                self.items = [(source, i) for i in range(len(initlist))]
+        assert len(self.data) == len(self.items), 'data mismatch'
+
+    def __str__(self):
+        return str(self.data)
+
+    def __repr__(self):
+        return '%s(%s, items=%s)' % (self.__class__.__name__,
+                                     self.data, self.items)
+
+    def __lt__(self, other): return self.data <  self.__cast(other)
+    def __le__(self, other): return self.data <= self.__cast(other)
+    def __eq__(self, other): return self.data == self.__cast(other)
+    def __ne__(self, other): return self.data != self.__cast(other)
+    def __gt__(self, other): return self.data >  self.__cast(other)
+    def __ge__(self, other): return self.data >= self.__cast(other)
+    def __cmp__(self, other): return cmp(self.data, self.__cast(other))
+
+    def __cast(self, other):
+        if isinstance(other, ViewList):
+            return other.data
+        else:
+            return other
+
+    def __contains__(self, item): return item in self.data
+    def __len__(self): return len(self.data)
+
+    # The __getitem__()/__setitem__() methods check whether the index
+    # is a slice first, since native list objects start supporting
+    # them directly in Python 2.3 (no exception is raised when
+    # indexing a list with a slice object; they just work).
+
+    def __getitem__(self, i):
+        if isinstance(i, _SliceType):
+            assert i.step in (None, 1),  'cannot handle slice with stride'
+            return self.__class__(self.data[i.start:i.stop],
+                                  items=self.items[i.start:i.stop],
+                                  parent=self, parent_offset=i.start)
+        else:
+            return self.data[i]
+
+    def __setitem__(self, i, item):
+        if isinstance(i, _SliceType):
+            assert i.step in (None, 1), 'cannot handle slice with stride'
+            if not isinstance(item, ViewList):
+                raise TypeError('assigning non-ViewList to ViewList slice')
+            self.data[i.start:i.stop] = item.data
+            self.items[i.start:i.stop] = item.items
+            assert len(self.data) == len(self.items), 'data mismatch'
+            if self.parent:
+                self.parent[i.start + self.parent_offset
+                            : i.stop + self.parent_offset] = item
+        else:
+            self.data[i] = item
+            if self.parent:
+                self.parent[i + self.parent_offset] = item
+
+    def __delitem__(self, i):
+        try:
+            del self.data[i]
+            del self.items[i]
+            if self.parent:
+                del self.parent[i + self.parent_offset]
+        except TypeError:
+            assert i.step is None, 'cannot handle slice with stride'
+            del self.data[i.start:i.stop]
+            del self.items[i.start:i.stop]
+            if self.parent:
+                del self.parent[i.start + self.parent_offset
+                                : i.stop + self.parent_offset]
+
+    def __add__(self, other):
+        if isinstance(other, ViewList):
+            return self.__class__(self.data + other.data,
+                                  items=(self.items + other.items))
+        else:
+            raise TypeError('adding non-ViewList to a ViewList')
+
+    def __radd__(self, other):
+        if isinstance(other, ViewList):
+            return self.__class__(other.data + self.data,
+                                  items=(other.items + self.items))
+        else:
+            raise TypeError('adding ViewList to a non-ViewList')
+
+    def __iadd__(self, other):
+        if isinstance(other, ViewList):
+            self.data += other.data
+        else:
+            raise TypeError('argument to += must be a ViewList')
+        return self
+
+    def __mul__(self, n):
+        return self.__class__(self.data * n, items=(self.items * n))
+
+    __rmul__ = __mul__
+
+    def __imul__(self, n):
+        self.data *= n
+        self.items *= n
+        return self
+
+    def extend(self, other):
+        if not isinstance(other, ViewList):
+            raise TypeError('extending a ViewList with a non-ViewList')
+        if self.parent:
+            self.parent.insert(len(self.data) + self.parent_offset, other)
+        self.data.extend(other.data)
+        self.items.extend(other.items)
+
+    def append(self, item, source=None, offset=0):
+        if source is None:
+            self.extend(item)
+        else:
+            if self.parent:
+                self.parent.insert(len(self.data) + self.parent_offset, item,
+                                   source, offset)
+            self.data.append(item)
+            self.items.append((source, offset))
+
+    def insert(self, i, item, source=None, offset=0):
+        if source is None:
+            if not isinstance(item, ViewList):
+                raise TypeError('inserting non-ViewList with no source given')
+            self.data[i:i] = item.data
+            self.items[i:i] = item.items
+            if self.parent:
+                index = (len(self.data) + i) % len(self.data)
+                self.parent.insert(index + self.parent_offset, item)
+        else:
+            self.data.insert(i, item)
+            self.items.insert(i, (source, offset))
+            if self.parent:
+                index = (len(self.data) + i) % len(self.data)
+                self.parent.insert(index + self.parent_offset, item,
+                                   source, offset)
+
+    def pop(self, i=-1):
+        if self.parent:
+            index = (len(self.data) + i) % len(self.data)
+            self.parent.pop(index + self.parent_offset)
+        self.items.pop(i)
+        return self.data.pop(i)
+
+    def trim_start(self, n=1):
+        """
+        Remove items from the start of the list, without touching the parent.
+        """
+        if n > len(self.data):
+            raise IndexError("Size of trim too large; can't trim %s items "
+                             "from a list of size %s." % (n, len(self.data)))
+        elif n < 0:
+            raise IndexError('Trim size must be >= 0.')
+        del self.data[:n]
+        del self.items[:n]
+        if self.parent:
+            self.parent_offset += n
+
+    def trim_end(self, n=1):
+        """
+        Remove items from the end of the list, without touching the parent.
+        """
+        if n > len(self.data):
+            raise IndexError("Size of trim too large; can't trim %s items "
+                             "from a list of size %s." % (n, len(self.data)))
+        elif n < 0:
+            raise IndexError('Trim size must be >= 0.')
+        del self.data[-n:]
+        del self.items[-n:]
+
+    def remove(self, item):
+        index = self.index(item)
+        del self[index]
+
+    def count(self, item): return self.data.count(item)
+    def index(self, item): return self.data.index(item)
+
+    def reverse(self):
+        self.data.reverse()
+        self.items.reverse()
+        self.parent = None
+
+    def sort(self, *args):
+        tmp = zip(self.data, self.items)
+        tmp.sort(*args)
+        self.data = [entry[0] for entry in tmp]
+        self.items = [entry[1] for entry in tmp]
+        self.parent = None
+
+    def info(self, i):
+        """Return source & offset for index `i`."""
+        try:
+            return self.items[i]
+        except IndexError:
+            if i == len(self.data):     # Just past the end
+                return self.items[i - 1][0], None
+            else:
+                raise
+
+    def source(self, i):
+        """Return source for index `i`."""
+        return self.info(i)[0]
+
+    def offset(self, i):
+        """Return offset for index `i`."""
+        return self.info(i)[1]
+
+    def disconnect(self):
+        """Break link between this list and parent list."""
+        self.parent = None
+
+
+class StringList(ViewList):
+
+    """A `ViewList` with string-specific methods."""
+
+    def strip_indent(self, length, start=0, end=sys.maxint):
+        """
+        Strip `length` characters off the beginning of each item, in-place,
+        from index `start` to `end`.  No whitespace-checking is done on the
+        stripped text.  Does not affect slice parent.
+        """
+        self.data[start:end] = [line[length:]
+                                for line in self.data[start:end]]
+
+    def get_text_block(self, start, flush_left=0):
+        """
+        Return a contiguous block of text.
+
+        If `flush_left` is true, raise `UnexpectedIndentationError` if an
+        indented line is encountered before the text block ends (with a blank
+        line).
+        """
+        end = start
+        last = len(self.data)
+        while end < last:
+            line = self.data[end]
+            if not line.strip():
+                break
+            if flush_left and (line[0] == ' '):
+                source, offset = self.info(end)
+                raise UnexpectedIndentationError(self[start:end], source,
+                                                 offset + 1)
+            end += 1
+        return self[start:end]
+
+    def get_indented(self, start=0, until_blank=0, strip_indent=1,
+                     block_indent=None, first_indent=None):
+        """
+        Extract and return a StringList of indented lines of text.
+
+        Collect all lines with indentation, determine the minimum indentation,
+        remove the minimum indentation from all indented lines (unless
+        `strip_indent` is false), and return them. All lines up to but not
+        including the first unindented line will be returned.
+
+        :Parameters:
+          - `start`: The index of the first line to examine.
+          - `until_blank`: Stop collecting at the first blank line if true.
+          - `strip_indent`: Strip common leading indent if true (default).
+          - `block_indent`: The indent of the entire block, if known.
+          - `first_indent`: The indent of the first line, if known.
+
+        :Return:
+          - a StringList of indented lines with mininum indent removed;
+          - the amount of the indent;
+          - a boolean: did the indented block finish with a blank line or EOF?
+        """
+        indent = block_indent           # start with None if unknown
+        end = start
+        if block_indent is not None and first_indent is None:
+            first_indent = block_indent
+        if first_indent is not None:
+            end += 1
+        last = len(self.data)
+        while end < last:
+            line = self.data[end]
+            if line and (line[0] != ' '
+                         or (block_indent is not None
+                             and line[:block_indent].strip())):
+                # Line not indented or insufficiently indented.
+                # Block finished properly iff the last indented line blank:
+                blank_finish = ((end > start)
+                                and not self.data[end - 1].strip())
+                break
+            stripped = line.lstrip()
+            if not stripped:            # blank line
+                if until_blank:
+                    blank_finish = 1
+                    break
+            elif block_indent is None:
+                line_indent = len(line) - len(stripped)
+                if indent is None:
+                    indent = line_indent
+                else:
+                    indent = min(indent, line_indent)
+            end += 1
+        else:
+            blank_finish = 1            # block ends at end of lines
+        block = self[start:end]
+        if first_indent is not None and block:
+            block.data[0] = block.data[0][first_indent:]
+        if indent and strip_indent:
+            block.strip_indent(indent, start=(first_indent is not None))
+        return block, indent or 0, blank_finish
+
+
+class StateMachineError(Exception): pass
+class UnknownStateError(StateMachineError): pass
+class DuplicateStateError(StateMachineError): pass
+class UnknownTransitionError(StateMachineError): pass
+class DuplicateTransitionError(StateMachineError): pass
+class TransitionPatternNotFound(StateMachineError): pass
+class TransitionMethodNotFound(StateMachineError): pass
+class UnexpectedIndentationError(StateMachineError): pass
+
+
+class TransitionCorrection(Exception):
+
+    """
+    Raise from within a transition method to switch to another transition.
+
+    Raise with one argument, the new transition name.
+    """
+
+
+class StateCorrection(Exception):
+
+    """
+    Raise from within a transition method to switch to another state.
+
+    Raise with one or two arguments: new state name, and an optional new
+    transition name.
+    """
+
+
+def string2lines(astring, tab_width=8, convert_whitespace=0,
+                 whitespace=re.compile('[\v\f]')):
+    """
+    Return a list of one-line strings with tabs expanded and no newlines.
+
+    Each tab is expanded with between 1 and `tab_width` spaces, so that the
+    next character's index becomes a multiple of `tab_width` (8 by default).
+
+    Parameters:
+
+    - `astring`: a multi-line string.
+    - `tab_width`: the number of columns between tab stops.
+    - `convert_whitespace`: convert form feeds and vertical tabs to spaces?
+    """
+    if convert_whitespace:
+        astring = whitespace.sub(' ', astring)
+    return [s.expandtabs(tab_width) for s in astring.splitlines()]
+
+def _exception_data():
+    """
+    Return exception information:
+
+    - the exception's class name;
+    - the exception object;
+    - the name of the file containing the offending code;
+    - the line number of the offending code;
+    - the function name of the offending code.
+    """
+    type, value, traceback = sys.exc_info()
+    while traceback.tb_next:
+        traceback = traceback.tb_next
+    code = traceback.tb_frame.f_code
+    return (type.__name__, value, code.co_filename, traceback.tb_lineno,
+            code.co_name)

lib/python/docutils/transforms/__init__.py

+# Authors: David Goodger, Ueli Schlaepfer
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:17 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+This package contains modules for standard tree transforms available
+to Docutils components. Tree transforms serve a variety of purposes:
+
+- To tie up certain syntax-specific "loose ends" that remain after the
+  initial parsing of the input plaintext. These transforms are used to
+  supplement a limited syntax.
+
+- To automate the internal linking of the document tree (hyperlink
+  references, footnote references, etc.).
+
+- To extract useful information from the document tree. These
+  transforms may be used to construct (for example) indexes and tables
+  of contents.
+
+Each transform is an optional step that a Docutils Reader may choose to
+perform on the parsed document, depending on the input context. A Docutils
+Reader may also perform Reader-specific transforms before or after performing
+these standard transforms.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+from docutils import languages, ApplicationError, TransformSpec
+
+
+class TransformError(ApplicationError): pass
+
+
+class Transform:
+
+    """
+    Docutils transform component abstract base class.
+    """
+
+    default_priority = None
+    """Numerical priority of this transform, 0 through 999 (override)."""
+
+    def __init__(self, document, startnode=None):
+        """
+        Initial setup for in-place document transforms.
+        """
+
+        self.document = document
+        """The document tree to transform."""
+
+        self.startnode = startnode
+        """Node from which to begin the transform.  For many transforms which
+        apply to the document as a whole, `startnode` is not set (i.e. its
+        value is `None`)."""
+
+        self.language = languages.get_language(
+            document.settings.language_code)
+        """Language module local to this document."""
+
+    def apply(self):
+        """Override to apply the transform to the document tree."""
+        raise NotImplementedError('subclass must override this method')
+
+
+class Transformer(TransformSpec):
+
+    """
+    Stores transforms (`Transform` classes) and applies them to document
+    trees.  Also keeps track of components by component type name.
+    """
+
+    from docutils.transforms import universal
+
+    default_transforms = (universal.Decorations,
+                          universal.FinalChecks,
+                          universal.Messages)
+    """These transforms are applied to all document trees."""
+
+    def __init__(self, document):
+        self.transforms = []
+        """List of transforms to apply.  Each item is a 3-tuple:
+        ``(priority string, transform class, pending node or None)``."""
+
+        self.document = document
+        """The `nodes.document` object this Transformer is attached to."""
+
+        self.applied = []
+        """Transforms already applied, in order."""
+
+        self.sorted = 0
+        """Boolean: is `self.tranforms` sorted?"""
+
+        self.components = {}
+        """Mapping of component type name to component object.  Set by
+        `self.populate_from_components()`."""
+
+        self.serialno = 0
+        """Internal serial number to keep track of the add order of
+        transforms."""
+
+    def add_transform(self, transform_class, priority=None):
+        """
+        Store a single transform.  Use `priority` to override the default.
+        """
+        if priority is None:
+            priority = transform_class.default_priority
+        priority_string = self.get_priority_string(priority)
+        self.transforms.append((priority_string, transform_class, None))
+        self.sorted = 0
+
+    def add_transforms(self, transform_list):
+        """Store multiple transforms, with default priorities."""
+        for transform_class in transform_list:
+            priority_string = self.get_priority_string(
+                transform_class.default_priority)
+            self.transforms.append((priority_string, transform_class, None))
+        self.sorted = 0
+
+    def add_pending(self, pending, priority=None):
+        """Store a transform with an associated `pending` node."""
+        transform_class = pending.transform
+        if priority is None:
+            priority = transform_class.default_priority
+        priority_string = self.get_priority_string(priority)
+        self.transforms.append((priority_string, transform_class, pending))
+        self.sorted = 0
+
+    def get_priority_string(self, priority):
+        """
+        Return a string, `priority` combined with `self.serialno`.
+
+        This ensures FIFO order on transforms with identical priority.
+        """
+        self.serialno += 1
+        return '%03d-%03d' % (priority, self.serialno)
+
+    def populate_from_components(self, components):
+        """
+        Store each component's default transforms, with default priorities.
+        Also, store components by type name in a mapping for later lookup.
+        """
+        self.add_transforms(self.default_transforms)
+        for component in components:
+            if component is None:
+                continue
+            self.add_transforms(component.default_transforms)
+            self.components[component.component_type] = component
+        self.sorted = 0
+
+    def apply_transforms(self):
+        """Apply all of the stored transforms, in priority order."""
+        self.document.reporter.attach_observer(
+            self.document.note_transform_message)
+        while self.transforms:
+            if not self.sorted:
+                # Unsorted initially, and whenever a transform is added.
+                self.transforms.sort()
+                self.transforms.reverse()
+                self.sorted = 1
+            priority, transform_class, pending = self.transforms.pop()
+            transform = transform_class(self.document, startnode=pending)
+            transform.apply()
+            self.applied.append((priority, transform_class, pending))

lib/python/docutils/transforms/components.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:17 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Docutils component-related transforms.
+"""
+
+__docformat__ = 'reStructuredText'
+
+import sys
+import os
+import re
+import time
+from docutils import nodes, utils
+from docutils import ApplicationError, DataError
+from docutils.transforms import Transform, TransformError
+
+
+class Filter(Transform):
+
+    """
+    Include or exclude elements which depend on a specific Docutils component.
+
+    For use with `nodes.pending` elements.  A "pending" element's dictionary
+    attribute ``details`` must contain the keys "component" and "format".  The
+    value of ``details['component']`` must match the type name of the
+    component the elements depend on (e.g. "writer").  The value of
+    ``details['format']`` is the name of a specific format or context of that
+    component (e.g. "html").  If the matching Docutils component supports that
+    format or context, the "pending" element is replaced by the contents of
+    ``details['nodes']`` (a list of nodes); otherwise, the "pending" element
+    is removed.
+
+    For example, the reStructuredText "meta" directive creates a "pending"
+    element containing a "meta" element (in ``pending.details['nodes']``).
+    Only writers (``pending.details['component'] == 'writer'``) supporting the
+    "html" format (``pending.details['format'] == 'html'``) will include the
+    "meta" element; it will be deleted from the output of all other writers.
+    """
+
+    default_priority = 780
+
+    def apply(self):
+        pending = self.startnode
+        component_type = pending.details['component'] # 'reader' or 'writer'
+        format = pending.details['format']
+        component = self.document.transformer.components[component_type]
+        if component.supports(format):
+            pending.parent.replace(pending, pending.details['nodes'])
+        else:
+            pending.parent.remove(pending)

lib/python/docutils/transforms/frontmatter.py

+# Authors: David Goodger, Ueli Schlaepfer
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:17 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Transforms related to the front matter of a document (information
+found before the main text):
+
+- `DocTitle`: Used to transform a lone top level section's title to
+  the document title, and promote a remaining lone top-level section's
+  title to the document subtitle.
+
+- `DocInfo`: Used to transform a bibliographic field list into docinfo
+  elements.
+"""
+
+__docformat__ = 'reStructuredText'
+
+import re
+from docutils import nodes, utils
+from docutils.transforms import TransformError, Transform
+
+
+class DocTitle(Transform):
+
+    """
+    In reStructuredText_, there is no way to specify a document title
+    and subtitle explicitly. Instead, we can supply the document title
+    (and possibly the subtitle as well) implicitly, and use this
+    two-step transform to "raise" or "promote" the title(s) (and their
+    corresponding section contents) to the document level.
+
+    1. If the document contains a single top-level section as its
+       first non-comment element, the top-level section's title
+       becomes the document's title, and the top-level section's
+       contents become the document's immediate contents. The lone
+       top-level section header must be the first non-comment element
+       in the document.
+
+       For example, take this input text::
+
+           =================
+            Top-Level Title
+           =================
+
+           A paragraph.
+
+       Once parsed, it looks like this::
+
+           <document>
+               <section name="top-level title">
+                   <title>
+                       Top-Level Title
+                   <paragraph>
+                       A paragraph.
+
+       After running the DocTitle transform, we have::
+
+           <document name="top-level title">
+               <title>
+                   Top-Level Title
+               <paragraph>
+                   A paragraph.
+
+    2. If step 1 successfully determines the document title, we
+       continue by checking for a subtitle.
+
+       If the lone top-level section itself contains a single
+       second-level section as its first non-comment element, that
+       section's title is promoted to the document's subtitle, and
+       that section's contents become the document's immediate
+       contents. Given this input text::
+
+           =================
+            Top-Level Title
+           =================
+
+           Second-Level Title
+           ~~~~~~~~~~~~~~~~~~
+
+           A paragraph.
+
+       After parsing and running the Section Promotion transform, the
+       result is::
+
+           <document name="top-level title">
+               <title>
+                   Top-Level Title
+               <subtitle name="second-level title">
+                   Second-Level Title
+               <paragraph>
+                   A paragraph.
+
+       (Note that the implicit hyperlink target generated by the
+       "Second-Level Title" is preserved on the "subtitle" element
+       itself.)
+
+    Any comment elements occurring before the document title or
+    subtitle are accumulated and inserted as the first body elements
+    after the title(s).
+    """
+
+    default_priority = 320
+
+    def apply(self):
+        if self.promote_document_title():
+            self.promote_document_subtitle()
+
+    def promote_document_title(self):
+        section, index = self.candidate_index()
+        if index is None:
+            return None
+        document = self.document
+        # Transfer the section's attributes to the document element (at root):
+        document.attributes.update(section.attributes)
+        document[:] = (section[:1]        # section title
+                       + document[:index] # everything that was in the
+                                          # document before the section
+                       + section[1:])     # everything that was in the section
+        return 1
+
+    def promote_document_subtitle(self):
+        subsection, index = self.candidate_index()
+        if index is None:
+            return None
+        subtitle = nodes.subtitle()
+        # Transfer the subsection's attributes to the new subtitle:
+        subtitle.attributes.update(subsection.attributes)
+        # Transfer the contents of the subsection's title to the subtitle:
+        subtitle[:] = subsection[0][:]
+        document = self.document
+        document[:] = (document[:1]       # document title
+                       + [subtitle]
+                       # everything that was before the section:
+                       + document[1:index]
+                       # everything that was in the subsection:
+                       + subsection[1:])
+        return 1
+
+    def candidate_index(self):
+        """
+        Find and return the promotion candidate and its index.
+
+        Return (None, None) if no valid candidate was found.
+        """
+        document = self.document
+        index = document.first_child_not_matching_class(
+              nodes.PreBibliographic)
+        if index is None or len(document) > (index + 1) or \
+              not isinstance(document[index], nodes.section):
+            return None, None
+        else:
+            return document[index], index
+
+
+class DocInfo(Transform):
+
+    """
+    This transform is specific to the reStructuredText_ markup syntax;
+    see "Bibliographic Fields" in the `reStructuredText Markup
+    Specification`_ for a high-level description. This transform
+    should be run *after* the `DocTitle` transform.
+
+    Given a field list as the first non-comment element after the
+    document title and subtitle (if present), registered bibliographic
+    field names are transformed to the corresponding DTD elements,
+    becoming child elements of the "docinfo" element (except for a
+    dedication and/or an abstract, which become "topic" elements after
+    "docinfo").
+
+    For example, given this document fragment after parsing::
+
+        <document>
+            <title>
+                Document Title
+            <field_list>
+                <field>
+                    <field_name>
+                        Author
+                    <field_body>
+                        <paragraph>
+                            A. Name
+                <field>
+                    <field_name>
+                        Status
+                    <field_body>
+                        <paragraph>
+                            $RCSfile: frontmatter.py,v $
+            ...
+
+    After running the bibliographic field list transform, the
+    resulting document tree would look like this::
+
+        <document>
+            <title>
+                Document Title
+            <docinfo>
+                <author>
+                    A. Name
+                <status>
+                    frontmatter.py
+            ...
+
+    The "Status" field contained an expanded RCS keyword, which is
+    normally (but optionally) cleaned up by the transform. The sole
+    contents of the field body must be a paragraph containing an
+    expanded RCS keyword of the form "$keyword: expansion text $". Any
+    RCS keyword can be processed in any bibliographic field. The
+    dollar signs and leading RCS keyword name are removed. Extra
+    processing is done for the following RCS keywords:
+
+    - "RCSfile" expands to the name of the file in the RCS or CVS
+      repository, which is the name of the source file with a ",v"
+      suffix appended. The transform will remove the ",v" suffix.
+
+    - "Date" expands to the format "YYYY/MM/DD hh:mm:ss" (in the UTC
+      time zone). The RCS Keywords transform will extract just the
+      date itself and transform it to an ISO 8601 format date, as in
+      "2000-12-31".
+
+      (Since the source file for this text is itself stored under CVS,
+      we can't show an example of the "Date" RCS keyword because we
+      can't prevent any RCS keywords used in this explanation from
+      being expanded. Only the "RCSfile" keyword is stable; its
+      expansion text changes only if the file name changes.)
+    """
+
+    default_priority = 340
+
+    def apply(self):
+        document = self.document
+        index = document.first_child_not_matching_class(
+              nodes.PreBibliographic)
+        if index is None:
+            return
+        candidate = document[index]
+        if isinstance(candidate, nodes.field_list):
+            biblioindex = document.first_child_not_matching_class(
+                  nodes.Titular)
+            nodelist = self.extract_bibliographic(candidate)
+            del document[index]         # untransformed field list (candidate)
+            document[biblioindex:biblioindex] = nodelist
+        return
+
+    def extract_bibliographic(self, field_list):
+        docinfo = nodes.docinfo()
+        bibliofields = self.language.bibliographic_fields
+        labels = self.language.labels
+        topics = {'dedication': None, 'abstract': None}
+        for field in field_list:
+            try:
+                name = field[0][0].astext()
+                normedname = utils.normalize_name(name)
+                if not (len(field) == 2 and bibliofields.has_key(normedname)
+                        and self.check_empty_biblio_field(field, name)):
+                    raise TransformError
+                biblioclass = bibliofields[normedname]
+                if issubclass(biblioclass, nodes.TextElement):
+                    if not self.check_compound_biblio_field(field, name):
+                        raise TransformError
+                    utils.clean_rcs_keywords(
+                          field[1][0], self.rcs_keyword_substitutions)
+                    docinfo.append(biblioclass('', '', *field[1][0]))
+                else:                   # multiple body elements possible
+                    if issubclass(biblioclass, nodes.authors):
+                        self.extract_authors(field, name, docinfo)
+                    elif issubclass(biblioclass, nodes.topic):
+                        if topics[normedname]:
+                            field[-1] += self.document.reporter.warning(
+                                  'There can only be one "%s" field.' % name,
+                                  base_node=field)
+                            raise TransformError
+                        title = nodes.title(name, labels[normedname])
+                        topics[normedname] = biblioclass(
+                            '', title, CLASS=normedname, *field[1].children)
+                    else:
+                        docinfo.append(biblioclass('', *field[1].children))
+            except TransformError:
+                if len(field[-1]) == 1 \
+                       and isinstance(field[-1][0], nodes.paragraph):
+                    utils.clean_rcs_keywords(
+                        field[-1][0], self.rcs_keyword_substitutions)
+                docinfo.append(field)
+                continue
+        nodelist = []
+        if len(docinfo) != 0:
+            nodelist.append(docinfo)
+        for name in ('dedication', 'abstract'):
+            if topics[name]:
+                nodelist.append(topics[name])
+        return nodelist
+
+    def check_empty_biblio_field(self, field, name):
+        if len(field[-1]) < 1:
+            field[-1] += self.document.reporter.warning(
+                  'Cannot extract empty bibliographic field "%s".' % name,
+                  base_node=field)
+            return None
+        return 1
+
+    def check_compound_biblio_field(self, field, name):
+        if len(field[-1]) > 1:
+            field[-1] += self.document.reporter.warning(
+                  'Cannot extract compound bibliographic field "%s".' % name,
+                  base_node=field)
+            return None
+        if not isinstance(field[-1][0], nodes.paragraph):
+            field[-1] += self.document.reporter.warning(
+                  'Cannot extract bibliographic field "%s" containing '
+                  'anything other than a single paragraph.' % name,
+                  base_node=field)
+            return None
+        return 1
+
+    rcs_keyword_substitutions = [
+          (re.compile(r'\$' r'Date: (\d\d\d\d)/(\d\d)/(\d\d) [\d:]+ \$$',
+                      re.IGNORECASE), r'\1-\2-\3'),
+          (re.compile(r'\$' r'RCSfile: (.+),v \$$', re.IGNORECASE), r'\1'),
+          (re.compile(r'\$[a-zA-Z]+: (.+) \$$'), r'\1'),]
+
+    def extract_authors(self, field, name, docinfo):
+        try:
+            if len(field[1]) == 1:
+                if isinstance(field[1][0], nodes.paragraph):
+                    authors = self.authors_from_one_paragraph(field)
+                elif isinstance(field[1][0], nodes.bullet_list):
+                    authors = self.authors_from_bullet_list(field)
+                else:
+                    raise TransformError
+            else:
+                authors = self.authors_from_paragraphs(field)
+            authornodes = [nodes.author('', '', *author)
+                           for author in authors if author]
+            if len(authornodes) > 1:
+                docinfo.append(nodes.authors('', *authornodes))
+            elif len(authornodes) == 1:
+                docinfo.append(authornodes[0])
+            else:
+                raise TransformError
+        except TransformError:
+            field[-1] += self.document.reporter.warning(
+                  'Bibliographic field "%s" incompatible with extraction: '
+                  'it must contain either a single paragraph (with authors '
+                  'separated by one of "%s"), multiple paragraphs (one per '
+                  'author), or a bullet list with one paragraph (one author) '
+                  'per item.'
+                  % (name, ''.join(self.language.author_separators)),
+                  base_node=field)
+            raise
+
+    def authors_from_one_paragraph(self, field):
+        text = field[1][0].astext().strip()
+        if not text:
+            raise TransformError
+        for authorsep in self.language.author_separators:
+            authornames = text.split(authorsep)
+            if len(authornames) > 1:
+                break
+        authornames = [author.strip() for author in authornames]
+        authors = [[nodes.Text(author)] for author in authornames if author]
+        return authors
+
+    def authors_from_bullet_list(self, field):
+        authors = []
+        for item in field[1][0]:
+            if len(item) != 1 or not isinstance(item[0], nodes.paragraph):
+                raise TransformError
+            authors.append(item[0].children)
+        if not authors:
+            raise TransformError
+        return authors
+
+    def authors_from_paragraphs(self, field):
+        for item in field[1]:
+            if not isinstance(item, nodes.paragraph):
+                raise TransformError
+        authors = [item.children for item in field[1]]
+        return authors

lib/python/docutils/transforms/misc.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:17 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Miscellaneous transforms.
+"""
+
+__docformat__ = 'reStructuredText'
+
+from docutils.transforms import Transform, TransformError
+
+
+class CallBack(Transform):
+
+    """
+    Inserts a callback into a document.  The callback is called when the
+    transform is applied, which is determined by its priority.
+
+    For use with `nodes.pending` elements.  Requires a ``details['callback']``
+    entry, a bound method or function which takes one parameter: the pending
+    node.  Other data can be stored in the ``details`` attribute or in the
+    object hosting the callback method.
+    """
+
+    default_priority = 990
+
+    def apply(self):
+        pending = self.startnode
+        pending.details['callback'](pending)
+        pending.parent.remove(pending)

lib/python/docutils/transforms/parts.py

+# Authors: David Goodger, Ueli Schlaepfer, Dmitry Jemerov
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:17 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Transforms related to document parts.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+import re
+import sys
+from docutils import nodes, utils
+from docutils.transforms import TransformError, Transform
+
+
+class SectNum(Transform):
+
+    """
+    Automatically assigns numbers to the titles of document sections.
+
+    It is possible to limit the maximum section level for which the numbers
+    are added.  For those sections that are auto-numbered, the "autonum"
+    attribute is set, informing the contents table generator that a different
+    form of the TOC should be used.
+    """
+
+    default_priority = 710
+    """Should be applied before `Contents`."""
+
+    def apply(self):
+        self.maxdepth = self.startnode.details.get('depth', sys.maxint)
+        self.startnode.parent.remove(self.startnode)
+        self.update_section_numbers(self.document)
+
+    def update_section_numbers(self, node, prefix=(), depth=0):
+        depth += 1
+        sectnum = 1
+        for child in node:
+            if isinstance(child, nodes.section):
+                numbers = prefix + (str(sectnum),)
+                title = child[0]
+                # Use   for spacing:
+                generated = nodes.generated(
+                    '', '.'.join(numbers) + u'\u00a0' * 3, CLASS='sectnum')
+                title.insert(0, generated)
+                title['auto'] = 1
+                if depth < self.maxdepth:
+                    self.update_section_numbers(child, numbers, depth)
+                sectnum += 1
+
+
+class Contents(Transform):
+
+    """
+    This transform generates a table of contents from the entire document tree
+    or from a single branch.  It locates "section" elements and builds them
+    into a nested bullet list, which is placed within a "topic".  A title is
+    either explicitly specified, taken from the appropriate language module,
+    or omitted (local table of contents).  The depth may be specified.
+    Two-way references between the table of contents and section titles are
+    generated (requires Writer support).
+
+    This transform requires a startnode, which which contains generation
+    options and provides the location for the generated table of contents (the
+    startnode is replaced by the table of contents "topic").
+    """
+
+    default_priority = 720
+
+    def apply(self):
+        topic = nodes.topic(CLASS='contents')
+        title = self.startnode.details['title']
+        if self.startnode.details.has_key('local'):
+            startnode = self.startnode.parent
+            # @@@ generate an error if the startnode (directive) not at
+            # section/document top-level? Drag it up until it is?
+            while not isinstance(startnode, nodes.Structural):
+                startnode = startnode.parent
+        else:
+            startnode = self.document
+            if not title:
+                title = nodes.title('', self.language.labels['contents'])
+        if title:
+            name = title.astext()
+            topic += title
+        else:
+            name = self.language.labels['contents']
+        name = utils.normalize_name(name)
+        if not self.document.has_name(name):
+            topic['name'] = name
+        self.document.note_implicit_target(topic)
+        self.toc_id = topic['id']
+        if self.startnode.details.has_key('backlinks'):
+            self.backlinks = self.startnode.details['backlinks']
+        else:
+            self.backlinks = self.document.settings.toc_backlinks
+        contents = self.build_contents(startnode)
+        if len(contents):
+            topic += contents
+            self.startnode.parent.replace(self.startnode, topic)
+        else:
+            self.startnode.parent.remove(self.startnode)
+
+    def build_contents(self, node, level=0):
+        level += 1
+        sections = []
+        i = len(node) - 1
+        while i >= 0 and isinstance(node[i], nodes.section):
+            sections.append(node[i])
+            i -= 1
+        sections.reverse()
+        entries = []
+        autonum = 0
+        depth = self.startnode.details.get('depth', sys.maxint)
+        for section in sections:
+            title = section[0]
+            auto = title.get('auto')    # May be set by SectNum.
+            entrytext = self.copy_and_filter(title)
+            reference = nodes.reference('', '', refid=section['id'],
+                                        *entrytext)
+            ref_id = self.document.set_id(reference)
+            entry = nodes.paragraph('', '', reference)
+            item = nodes.list_item('', entry)
+            if self.backlinks == 'entry':
+                title['refid'] = ref_id
+            elif self.backlinks == 'top':
+                title['refid'] = self.toc_id
+            if level < depth:
+                subsects = self.build_contents(section, level)
+                item += subsects
+            entries.append(item)
+        if entries:
+            contents = nodes.bullet_list('', *entries)
+            if auto:
+                contents.set_class('auto-toc')
+            return contents
+        else:
+            return []
+
+    def copy_and_filter(self, node):
+        """Return a copy of a title, with references, images, etc. removed."""
+        visitor = ContentsFilter(self.document)
+        node.walkabout(visitor)
+        return visitor.get_entry_text()
+
+
+class ContentsFilter(nodes.TreeCopyVisitor):
+
+    def get_entry_text(self):
+        return self.get_tree_copy().get_children()
+
+    def visit_citation_reference(self, node):
+        raise nodes.SkipNode
+
+    def visit_footnote_reference(self, node):
+        raise nodes.SkipNode
+
+    def visit_image(self, node):
+        if node.hasattr('alt'):
+            self.parent.append(nodes.Text(node['alt']))
+        raise nodes.SkipNode
+
+    def ignore_node_but_process_children(self, node):
+        raise nodes.SkipDeparture
+
+    visit_interpreted = ignore_node_but_process_children
+    visit_problematic = ignore_node_but_process_children
+    visit_reference = ignore_node_but_process_children
+    visit_target = ignore_node_but_process_children

lib/python/docutils/transforms/peps.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:17 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Transforms for PEP processing.
+
+- `Headers`: Used to transform a PEP's initial RFC-2822 header.  It remains a
+  field list, but some entries get processed.
+- `Contents`: Auto-inserts a table of contents.
+- `PEPZero`: Special processing for PEP 0.
+"""
+
+__docformat__ = 'reStructuredText'
+
+import sys
+import os
+import re
+import time
+from docutils import nodes, utils
+from docutils import ApplicationError, DataError
+from docutils.transforms import Transform, TransformError
+from docutils.transforms import parts, references, misc
+
+
+class Headers(Transform):
+
+    """
+    Process fields in a PEP's initial RFC-2822 header.
+    """
+
+    default_priority = 360
+
+    pep_url = 'pep-%04d.html'
+    pep_cvs_url = ('http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/python/'
+                   'python/nondist/peps/pep-%04d.txt')
+    rcs_keyword_substitutions = (
+          (re.compile(r'\$' r'RCSfile: (.+),v \$$', re.IGNORECASE), r'\1'),
+          (re.compile(r'\$[a-zA-Z]+: (.+) \$$'), r'\1'),)
+
+    def apply(self):
+        if not len(self.document):
+            # @@@ replace these DataErrors with proper system messages
+            raise DataError('Document tree is empty.')
+        header = self.document[0]
+        if not isinstance(header, nodes.field_list) or \
+              header.get('class') != 'rfc2822':
+            raise DataError('Document does not begin with an RFC-2822 '
+                            'header; it is not a PEP.')
+        pep = None
+        for field in header:
+            if field[0].astext().lower() == 'pep': # should be the first field
+                value = field[1].astext()
+                try:
+                    pep = int(value)
+                    cvs_url = self.pep_cvs_url % pep
+                except ValueError:
+                    pep = value
+                    cvs_url = None
+                    msg = self.document.reporter.warning(
+                        '"PEP" header must contain an integer; "%s" is an '
+                        'invalid value.' % pep, base_node=field)
+                    msgid = self.document.set_id(msg)
+                    prb = nodes.problematic(value, value or '(none)',
+                                            refid=msgid)
+                    prbid = self.document.set_id(prb)
+                    msg.add_backref(prbid)
+                    if len(field[1]):
+                        field[1][0][:] = [prb]
+                    else:
+                        field[1] += nodes.paragraph('', '', prb)
+                break
+        if pep is None:
+            raise DataError('Document does not contain an RFC-2822 "PEP" '
+                            'header.')
+        if pep == 0:
+            # Special processing for PEP 0.
+            pending = nodes.pending(PEPZero)
+            self.document.insert(1, pending)
+            self.document.note_pending(pending)
+        if len(header) < 2 or header[1][0].astext().lower() != 'title':
+            raise DataError('No title!')
+        for field in header:
+            name = field[0].astext().lower()
+            body = field[1]
+            if len(body) > 1:
+                raise DataError('PEP header field body contains multiple '
+                                'elements:\n%s' % field.pformat(level=1))
+            elif len(body) == 1:
+                if not isinstance(body[0], nodes.paragraph):
+                    raise DataError('PEP header field body may only contain '
+                                    'a single paragraph:\n%s'
+                                    % field.pformat(level=1))
+            elif name == 'last-modified':
+                date = time.strftime(
+                      '%d-%b-%Y',
+                      time.localtime(os.stat(self.document['source'])[8]))
+                if cvs_url:
+                    body += nodes.paragraph(
+                        '', '', nodes.reference('', date, refuri=cvs_url))
+            else:
+                # empty
+                continue
+            para = body[0]
+            if name == 'author':
+                for node in para:
+                    if isinstance(node, nodes.reference):
+                        node.parent.replace(node, mask_email(node))
+            elif name == 'discussions-to':
+                for node in para:
+                    if isinstance(node, nodes.reference):
+                        node.parent.replace(node, mask_email(node, pep))
+            elif name in ('replaces', 'replaced-by', 'requires'):
+                newbody = []
+                space = nodes.Text(' ')
+                for refpep in re.split(',?\s+', body.astext()):
+                    pepno = int(refpep)
+                    newbody.append(nodes.reference(
+                          refpep, refpep, refuri=self.pep_url % pepno))
+                    newbody.append(space)
+                para[:] = newbody[:-1] # drop trailing space
+            elif name == 'last-modified':
+                utils.clean_rcs_keywords(para, self.rcs_keyword_substitutions)
+                if cvs_url:
+                    date = para.astext()
+                    para[:] = [nodes.reference('', date, refuri=cvs_url)]
+            elif name == 'content-type':
+                pep_type = para.astext()
+                uri = self.pep_url % 12
+                para[:] = [nodes.reference('', pep_type, refuri=uri)]
+            elif name == 'version' and len(body):
+                utils.clean_rcs_keywords(para, self.rcs_keyword_substitutions)
+
+
+class Contents(Transform):
+
+    """
+    Insert a table of contents transform placeholder into the document after
+    the RFC 2822 header.
+    """
+
+    default_priority = 380
+
+    def apply(self):
+        pending = nodes.pending(parts.Contents, {'title': None})
+        self.document.insert(1, pending)
+        self.document.note_pending(pending)
+
+
+class TargetNotes(Transform):
+
+    """
+    Locate the "References" section, insert a placeholder for an external
+    target footnote insertion transform at the end, and schedule the
+    transform to run immediately.
+    """
+
+    default_priority = 520
+
+    def apply(self):
+        doc = self.document
+        i = len(doc) - 1
+        refsect = copyright = None
+        while i >= 0 and isinstance(doc[i], nodes.section):
+            title_words = doc[i][0].astext().lower().split()
+            if 'references' in title_words:
+                refsect = doc[i]
+                break
+            elif 'copyright' in title_words:
+                copyright = i
+            i -= 1
+        if not refsect:
+            refsect = nodes.section()
+            refsect += nodes.title('', 'References')
+            doc.set_id(refsect)
+            if copyright:
+                # Put the new "References" section before "Copyright":
+                doc.insert(copyright, refsect)
+            else:
+                # Put the new "References" section at end of doc:
+                doc.append(refsect)
+        pending = nodes.pending(references.TargetNotes)
+        refsect.append(pending)
+        self.document.note_pending(pending, 0)
+        pending = nodes.pending(misc.CallBack,
+                                details={'callback': self.cleanup_callback})
+        refsect.append(pending)
+        self.document.note_pending(pending, 1)
+
+    def cleanup_callback(self, pending):
+        """
+        Remove an empty "References" section.
+
+        Called after the `references.TargetNotes` transform is complete.
+        """
+        if len(pending.parent) == 2:    # <title> and <pending>
+            pending.parent.parent.remove(pending.parent)
+
+
+class PEPZero(Transform):
+
+    """
+    Special processing for PEP 0.
+    """
+
+    default_priority =760
+
+    def apply(self):
+        visitor = PEPZeroSpecial(self.document)
+        self.document.walk(visitor)
+        self.startnode.parent.remove(self.startnode)
+
+
+class PEPZeroSpecial(nodes.SparseNodeVisitor):
+
+    """
+    Perform the special processing needed by PEP 0:
+
+    - Mask email addresses.
+
+    - Link PEP numbers in the second column of 4-column tables to the PEPs
+      themselves.
+    """
+
+    pep_url = Headers.pep_url
+
+    def unknown_visit(self, node):
+        pass
+
+    def visit_reference(self, node):
+        node.parent.replace(node, mask_email(node))
+
+    def visit_field_list(self, node):
+        if node.hasattr('class') and node['class'] == 'rfc2822':
+            raise nodes.SkipNode
+
+    def visit_tgroup(self, node):
+        self.pep_table = node['cols'] == 4
+        self.entry = 0
+
+    def visit_colspec(self, node):
+        self.entry += 1
+        if self.pep_table and self.entry == 2:
+            node['class'] = 'num'
+
+    def visit_row(self, node):
+        self.entry = 0
+
+    def visit_entry(self, node):
+        self.entry += 1
+        if self.pep_table and self.entry == 2 and len(node) == 1:
+            node['class'] = 'num'
+            p = node[0]
+            if isinstance(p, nodes.paragraph) and len(p) == 1:
+                text = p.astext()
+                try:
+                    pep = int(text)
+                    ref = self.pep_url % pep
+                    p[0] = nodes.reference(text, text, refuri=ref)
+                except ValueError:
+                    pass
+
+
+non_masked_addresses = ('peps@python.org',
+                        'python-list@python.org',
+                        'python-dev@python.org')
+
+def mask_email(ref, pepno=None):
+    """
+    Mask the email address in `ref` and return a replacement node.
+
+    `ref` is returned unchanged if it contains no email address.
+
+    For email addresses such as "user@host", mask the address as "user at
+    host" (text) to thwart simple email address harvesters (except for those
+    listed in `non_masked_addresses`).  If a PEP number (`pepno`) is given,
+    return a reference including a default email subject.
+    """
+    if ref.hasattr('refuri') and ref['refuri'].startswith('mailto:'):
+        if ref['refuri'][8:] in non_masked_addresses:
+            replacement = ref[0]
+        else:
+            replacement_text = ref.astext().replace('@', '&#32;&#97;t&#32;')
+            replacement = nodes.raw('', replacement_text, format='html')
+        if pepno is None:
+            return replacement
+        else:
+            ref['refuri'] += '?subject=PEP%%20%s' % pepno
+            ref[:] = [replacement]
+            return ref
+    else:
+        return ref

lib/python/docutils/transforms/references.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:17 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Transforms for resolving references.
+"""
+
+__docformat__ = 'reStructuredText'
+
+import sys
+import re
+from docutils import nodes, utils
+from docutils.transforms import TransformError, Transform
+
+
+indices = xrange(sys.maxint)
+
+
+class ChainedTargets(Transform):
+
+    """
+    Attributes "refuri" and "refname" are migrated from the final direct
+    target up the chain of contiguous adjacent internal targets, using
+    `ChainedTargetResolver`.
+    """
+
+    default_priority = 420
+
+    def apply(self):
+        visitor = ChainedTargetResolver(self.document)
+        self.document.walk(visitor)
+
+
+class ChainedTargetResolver(nodes.SparseNodeVisitor):
+
+    """
+    Copy reference attributes up the length of a hyperlink target chain.
+
+    "Chained targets" are multiple adjacent internal hyperlink targets which
+    "point to" an external or indirect target.  After the transform, all
+    chained targets will effectively point to the same place.
+
+    Given the following ``document`` as input::
+
+        <document>
+            <target id="a" name="a">
+            <target id="b" name="b">
+            <target id="c" name="c" refuri="http://chained.external.targets">
+            <target id="d" name="d">
+            <paragraph>
+                I'm known as "d".
+            <target id="e" name="e">
+            <target id="id1">
+            <target id="f" name="f" refname="d">
+
+    ``ChainedTargetResolver(document).walk()`` will transform the above into::
+
+        <document>
+            <target id="a" name="a" refuri="http://chained.external.targets">
+            <target id="b" name="b" refuri="http://chained.external.targets">
+            <target id="c" name="c" refuri="http://chained.external.targets">
+            <target id="d" name="d">
+            <paragraph>
+                I'm known as "d".
+            <target id="e" name="e" refname="d">
+            <target id="id1" refname="d">
+            <target id="f" name="f" refname="d">
+    """
+
+    def unknown_visit(self, node):
+        pass
+
+    def visit_target(self, node):
+        if node.hasattr('refuri'):
+            attname = 'refuri'
+            call_if_named = self.document.note_external_target
+        elif node.hasattr('refname'):
+            attname = 'refname'
+            call_if_named = self.document.note_indirect_target
+        elif node.hasattr('refid'):
+            attname = 'refid'
+            call_if_named = None
+        else:
+            return
+        attval = node[attname]
+        index = node.parent.index(node)
+        for i in range(index - 1, -1, -1):
+            sibling = node.parent[i]
+            if not isinstance(sibling, nodes.target) \
+                  or sibling.hasattr('refuri') \
+                  or sibling.hasattr('refname') \
+                  or sibling.hasattr('refid'):
+                break
+            sibling[attname] = attval
+            if sibling.hasattr('name') and call_if_named:
+                call_if_named(sibling)
+
+
+class AnonymousHyperlinks(Transform):
+
+    """
+    Link anonymous references to targets.  Given::
+
+        <paragraph>
+            <reference anonymous="1">
+                internal
+            <reference anonymous="1">
+                external
+        <target anonymous="1" id="id1">
+        <target anonymous="1" id="id2" refuri="http://external">
+
+    Corresponding references are linked via "refid" or resolved via "refuri"::
+
+        <paragraph>
+            <reference anonymous="1" refid="id1">
+                text
+            <reference anonymous="1" refuri="http://external">
+                external
+        <target anonymous="1" id="id1">
+        <target anonymous="1" id="id2" refuri="http://external">
+    """
+
+    default_priority = 440
+
+    def apply(self):
+        if len(self.document.anonymous_refs) \
+              != len(self.document.anonymous_targets):
+            msg = self.document.reporter.error(
+                  'Anonymous hyperlink mismatch: %s references but %s '
+                  'targets.\nSee "backrefs" attribute for IDs.'
+                  % (len(self.document.anonymous_refs),
+                     len(self.document.anonymous_targets)))
+            msgid = self.document.set_id(msg)
+            for ref in self.document.anonymous_refs:
+                prb = nodes.problematic(
+                      ref.rawsource, ref.rawsource, refid=msgid)
+                prbid = self.document.set_id(prb)
+                msg.add_backref(prbid)
+                ref.parent.replace(ref, prb)
+            return
+        for ref, target in zip(self.document.anonymous_refs,
+                               self.document.anonymous_targets):
+            if target.hasattr('refuri'):
+                ref['refuri'] = target['refuri']
+                ref.resolved = 1
+            else:
+                ref['refid'] = target['id']
+                self.document.note_refid(ref)
+            target.referenced = 1
+
+
+class IndirectHyperlinks(Transform):
+
+    """
+    a) Indirect external references::
+
+           <paragraph>
+               <reference refname="indirect external">
+                   indirect external
+           <target id="id1" name="direct external"
+               refuri="http://indirect">
+           <target id="id2" name="indirect external"
+               refname="direct external">
+
+       The "refuri" attribute is migrated back to all indirect targets
+       from the final direct target (i.e. a target not referring to
+       another indirect target)::
+
+           <paragraph>
+               <reference refname="indirect external">
+                   indirect external
+           <target id="id1" name="direct external"
+               refuri="http://indirect">
+           <target id="id2" name="indirect external"
+               refuri="http://indirect">
+
+       Once the attribute is migrated, the preexisting "refname" attribute
+       is dropped.
+
+    b) Indirect internal references::
+
+           <target id="id1" name="final target">
+           <paragraph>
+               <reference refname="indirect internal">
+                   indirect internal
+           <target id="id2" name="indirect internal 2"
+               refname="final target">
+           <target id="id3" name="indirect internal"
+               refname="indirect internal 2">
+
+       Targets which indirectly refer to an internal target become one-hop
+       indirect (their "refid" attributes are directly set to the internal
+       target's "id"). References which indirectly refer to an internal
+       target become direct internal references::
+
+           <target id="id1" name="final target">
+           <paragraph>
+               <reference refid="id1">
+                   indirect internal
+           <target id="id2" name="indirect internal 2" refid="id1">
+           <target id="id3" name="indirect internal" refid="id1">
+    """
+
+    default_priority = 460
+
+    def apply(self):
+        for target in self.document.indirect_targets:
+            if not target.resolved:
+                self.resolve_indirect_target(target)
+            self.resolve_indirect_references(target)
+
+    def resolve_indirect_target(self, target):
+        refname = target['refname']
+        reftarget_id = self.document.nameids.get(refname)
+        if not reftarget_id:
+            self.nonexistent_indirect_target(target)
+            return
+        reftarget = self.document.ids[reftarget_id]
+        if isinstance(reftarget, nodes.target) \
+              and not reftarget.resolved and reftarget.hasattr('refname'):
+            if hasattr(target, 'multiply_indirect'):
+                #and target.multiply_indirect):
+                #del target.multiply_indirect
+                self.circular_indirect_reference(target)
+                return
+            target.multiply_indirect = 1
+            self.resolve_indirect_target(reftarget) # multiply indirect
+            del target.multiply_indirect
+        if reftarget.hasattr('refuri'):
+            target['refuri'] = reftarget['refuri']
+            if target.hasattr('name'):
+                self.document.note_external_target(target)
+        elif reftarget.hasattr('refid'):
+            target['refid'] = reftarget['refid']
+            self.document.note_refid(target)
+        else:
+            try:
+                target['refid'] = reftarget['id']
+                self.document.note_refid(target)
+            except KeyError:
+                self.nonexistent_indirect_target(target)
+                return
+        del target['refname']
+        target.resolved = 1
+        reftarget.referenced = 1
+
+    def nonexistent_indirect_target(self, target):
+        self.indirect_target_error(target, 'which does not exist')
+
+    def circular_indirect_reference(self, target):
+        self.indirect_target_error(target, 'forming a circular reference')
+
+    def indirect_target_error(self, target, explanation):
+        naming = ''
+        if target.hasattr('name'):
+            naming = '"%s" ' % target['name']
+            reflist = self.document.refnames.get(target['name'], [])
+        else:
+            reflist = self.document.refids.get(target['id'], [])
+        naming += '(id="%s")' % target['id']
+        msg = self.document.reporter.error(
+              'Indirect hyperlink target %s refers to target "%s", %s.'
+              % (naming, target['refname'], explanation),
+              base_node=target)
+        msgid = self.document.set_id(msg)
+        for ref in reflist:
+            prb = nodes.problematic(
+                  ref.rawsource, ref.rawsource, refid=msgid)
+            prbid = self.document.set_id(prb)
+            msg.add_backref(prbid)
+            ref.parent.replace(ref, prb)
+        target.resolved = 1
+
+    def resolve_indirect_references(self, target):
+        if target.hasattr('refid'):
+            attname = 'refid'
+            call_if_named = 0
+            call_method = self.document.note_refid
+        elif target.hasattr('refuri'):
+            attname = 'refuri'
+            call_if_named = 1
+            call_method = self.document.note_external_target
+        else:
+            return
+        attval = target[attname]
+        if target.hasattr('name'):
+            name = target['name']
+            try:
+                reflist = self.document.refnames[name]
+            except KeyError, instance:
+                if target.referenced:
+                    return
+                msg = self.document.reporter.info(
+                      'Indirect hyperlink target "%s" is not referenced.'
+                      % name, base_node=target)
+                target.referenced = 1
+                return
+            delatt = 'refname'
+        else:
+            id = target['id']
+            try:
+                reflist = self.document.refids[id]
+            except KeyError, instance:
+                if target.referenced:
+                    return
+                msg = self.document.reporter.info(
+                      'Indirect hyperlink target id="%s" is not referenced.'
+                      % id, base_node=target)
+                target.referenced = 1
+                return
+            delatt = 'refid'
+        for ref in reflist:
+            if ref.resolved:
+                continue
+            del ref[delatt]
+            ref[attname] = attval
+            if not call_if_named or ref.hasattr('name'):
+                call_method(ref)
+            ref.resolved = 1
+            if isinstance(ref, nodes.target):
+                self.resolve_indirect_references(ref)
+        target.referenced = 1
+
+
+class ExternalTargets(Transform):
+
+    """
+    Given::
+
+        <paragraph>
+            <reference refname="direct external">
+                direct external
+        <target id="id1" name="direct external" refuri="http://direct">
+
+    The "refname" attribute is replaced by the direct "refuri" attribute::
+
+        <paragraph>
+            <reference refuri="http://direct">
+                direct external
+        <target id="id1" name="direct external" refuri="http://direct">
+    """
+
+    default_priority = 640
+
+    def apply(self):
+        for target in self.document.external_targets:
+            if target.hasattr('refuri') and target.hasattr('name'):
+                name = target['name']
+                refuri = target['refuri']
+                try:
+                    reflist = self.document.refnames[name]
+                except KeyError, instance:
+                    if target.referenced:
+                        continue
+                    msg = self.document.reporter.info(
+                          'External hyperlink target "%s" is not referenced.'
+                          % name, base_node=target)
+                    target.referenced = 1
+                    continue
+                for ref in reflist:
+                    if ref.resolved:
+                        continue
+                    del ref['refname']
+                    ref['refuri'] = refuri
+                    ref.resolved = 1
+                target.referenced = 1
+
+
+class InternalTargets(Transform):
+
+    """
+    Given::
+
+        <paragraph>
+            <reference refname="direct internal">
+                direct internal
+        <target id="id1" name="direct internal">
+
+    The "refname" attribute is replaced by "refid" linking to the target's
+    "id"::
+
+        <paragraph>
+            <reference refid="id1">
+                direct internal
+        <target id="id1" name="direct internal">
+    """
+
+    default_priority = 660
+
+    def apply(self):
+        for target in self.document.internal_targets:
+            if target.hasattr('refuri') or target.hasattr('refid') \
+                  or not target.hasattr('name'):
+                continue
+            name = target['name']
+            refid = target['id']
+            try:
+                reflist = self.document.refnames[name]
+            except KeyError, instance:
+                if target.referenced:
+                    continue
+                msg = self.document.reporter.info(
+                      'Internal hyperlink target "%s" is not referenced.'
+                      % name, base_node=target)
+                target.referenced = 1
+                continue
+            for ref in reflist:
+                if ref.resolved:
+                    continue
+                del ref['refname']
+                ref['refid'] = refid
+                ref.resolved = 1
+            target.referenced = 1
+
+
+class Footnotes(Transform):
+
+    """
+    Assign numbers to autonumbered footnotes, and resolve links to footnotes,
+    citations, and their references.
+
+    Given the following ``document`` as input::
+
+        <document>
+            <paragraph>
+                A labeled autonumbered footnote referece:
+                <footnote_reference auto="1" id="id1" refname="footnote">
+            <paragraph>
+                An unlabeled autonumbered footnote referece:
+                <footnote_reference auto="1" id="id2">
+            <footnote auto="1" id="id3">
+                <paragraph>
+                    Unlabeled autonumbered footnote.
+            <footnote auto="1" id="footnote" name="footnote">
+                <paragraph>
+                    Labeled autonumbered footnote.
+
+    Auto-numbered footnotes have attribute ``auto="1"`` and no label.
+    Auto-numbered footnote_references have no reference text (they're
+    empty elements). When resolving the numbering, a ``label`` element
+    is added to the beginning of the ``footnote``, and reference text
+    to the ``footnote_reference``.
+
+    The transformed result will be::
+
+        <document>
+            <paragraph>
+                A labeled autonumbered footnote referece:
+                <footnote_reference auto="1" id="id1" refid="footnote">
+                    2
+            <paragraph>
+                An unlabeled autonumbered footnote referece:
+                <footnote_reference auto="1" id="id2" refid="id3">
+                    1
+            <footnote auto="1" id="id3" backrefs="id2">
+                <label>
+                    1
+                <paragraph>
+                    Unlabeled autonumbered footnote.
+            <footnote auto="1" id="footnote" name="footnote" backrefs="id1">
+                <label>
+                    2
+                <paragraph>
+                    Labeled autonumbered footnote.
+
+    Note that the footnotes are not in the same order as the references.
+
+    The labels and reference text are added to the auto-numbered ``footnote``
+    and ``footnote_reference`` elements.  Footnote elements are backlinked to
+    their references via "refids" attributes.  References are assigned "id"
+    and "refid" attributes.
+
+    After adding labels and reference text, the "auto" attributes can be
+    ignored.
+    """
+
+    default_priority = 620
+
+    autofootnote_labels = None
+    """Keep track of unlabeled autonumbered footnotes."""
+
+    symbols = [
+          # Entries 1-4 and 6 below are from section 12.51 of
+          # The Chicago Manual of Style, 14th edition.
+          '*',                          # asterisk/star
+          u'\u2020',                    # dagger &dagger;
+          u'\u2021',                    # double dagger &Dagger;
+          u'\u00A7',                    # section mark &sect;
+          u'\u00B6',                    # paragraph mark (pilcrow) &para;
+                                        # (parallels ['||'] in CMoS)
+          '#',                          # number sign
+          # The entries below were chosen arbitrarily.
+          u'\u2660',                    # spade suit &spades;
+          u'\u2665',                    # heart suit &hearts;
+          u'\u2666',                    # diamond suit &diams;
+          u'\u2663',                    # club suit &clubs;
+          ]
+
+    def apply(self):
+        self.autofootnote_labels = []
+        startnum = self.document.autofootnote_start
+        self.document.autofootnote_start = self.number_footnotes(startnum)
+        self.number_footnote_references(startnum)
+        self.symbolize_footnotes()
+        self.resolve_footnotes_and_citations()
+
+    def number_footnotes(self, startnum):
+        """
+        Assign numbers to autonumbered footnotes.
+
+        For labeled autonumbered footnotes, copy the number over to
+        corresponding footnote references.
+        """
+        for footnote in self.document.autofootnotes:
+            while 1:
+                label = str(startnum)
+                startnum += 1
+                if not self.document.nameids.has_key(label):
+                    break
+            footnote.insert(0, nodes.label('', label))
+            if footnote.hasattr('dupname'):
+                continue
+            if footnote.hasattr('name'):
+                name = footnote['name']
+                for ref in self.document.footnote_refs.get(name, []):
+                    ref += nodes.Text(label)
+                    ref.delattr('refname')
+                    ref['refid'] = footnote['id']
+                    footnote.add_backref(ref['id'])
+                    self.document.note_refid(ref)
+                    ref.resolved = 1
+            else:
+                footnote['name'] = label
+                self.document.note_explicit_target(footnote, footnote)
+                self.autofootnote_labels.append(label)
+        return startnum
+
+    def number_footnote_references(self, startnum):
+        """Assign numbers to autonumbered footnote references."""
+        i = 0
+        for ref in self.document.autofootnote_refs:
+            if ref.resolved or ref.hasattr('refid'):
+                continue
+            try:
+                label = self.autofootnote_labels[i]
+            except IndexError:
+                msg = self.document.reporter.error(
+                      'Too many autonumbered footnote references: only %s '
+                      'corresponding footnotes available.'
+                      % len(self.autofootnote_labels), base_node=ref)
+                msgid = self.document.set_id(msg)
+                for ref in self.document.autofootnote_refs[i:]:
+                    if ref.resolved or ref.hasattr('refname'):
+                        continue
+                    prb = nodes.problematic(
+                          ref.rawsource, ref.rawsource, refid=msgid)
+                    prbid = self.document.set_id(prb)
+                    msg.add_backref(prbid)
+                    ref.parent.replace(ref, prb)
+                break
+            ref += nodes.Text(label)
+            id = self.document.nameids[label]
+            footnote = self.document.ids[id]
+            ref['refid'] = id
+            self.document.note_refid(ref)
+            footnote.add_backref(ref['id'])
+            ref.resolved = 1
+            i += 1
+
+    def symbolize_footnotes(self):
+        """Add symbols indexes to "[*]"-style footnotes and references."""
+        labels = []
+        for footnote in self.document.symbol_footnotes:
+            reps, index = divmod(self.document.symbol_footnote_start,
+                                 len(self.symbols))
+            labeltext = self.symbols[index] * (reps + 1)
+            labels.append(labeltext)
+            footnote.insert(0, nodes.label('', labeltext))
+            self.document.symbol_footnote_start += 1
+            self.document.set_id(footnote)
+        i = 0
+        for ref in self.document.symbol_footnote_refs:
+            try:
+                ref += nodes.Text(labels[i])
+            except IndexError:
+                msg = self.document.reporter.error(
+                      'Too many symbol footnote references: only %s '
+                      'corresponding footnotes available.' % len(labels),
+                      base_node=ref)
+                msgid = self.document.set_id(msg)
+                for ref in self.document.symbol_footnote_refs[i:]:
+                    if ref.resolved or ref.hasattr('refid'):
+                        continue
+                    prb = nodes.problematic(
+                          ref.rawsource, ref.rawsource, refid=msgid)
+                    prbid = self.document.set_id(prb)
+                    msg.add_backref(prbid)
+                    ref.parent.replace(ref, prb)
+                break
+            footnote = self.document.symbol_footnotes[i]
+            ref['refid'] = footnote['id']
+            self.document.note_refid(ref)
+            footnote.add_backref(ref['id'])
+            i += 1
+
+    def resolve_footnotes_and_citations(self):
+        """
+        Link manually-labeled footnotes and citations to/from their
+        references.
+        """
+        for footnote in self.document.footnotes:
+            label = footnote['name']
+            if self.document.footnote_refs.has_key(label):
+                reflist = self.document.footnote_refs[label]
+                self.resolve_references(footnote, reflist)
+        for citation in self.document.citations:
+            label = citation['name']
+            if self.document.citation_refs.has_key(label):
+                reflist = self.document.citation_refs[label]
+                self.resolve_references(citation, reflist)
+
+    def resolve_references(self, note, reflist):
+        id = note['id']
+        for ref in reflist:
+            if ref.resolved:
+                continue
+            ref.delattr('refname')
+            ref['refid'] = id
+            note.add_backref(ref['id'])
+            ref.resolved = 1
+        note.resolved = 1
+
+
+class Substitutions(Transform):
+
+    """
+    Given the following ``document`` as input::
+
+        <document>
+            <paragraph>
+                The
+                <substitution_reference refname="biohazard">
+                    biohazard
+                 symbol is deservedly scary-looking.
+            <substitution_definition name="biohazard">
+                <image alt="biohazard" uri="biohazard.png">
+
+    The ``substitution_reference`` will simply be replaced by the
+    contents of the corresponding ``substitution_definition``.
+
+    The transformed result will be::
+
+        <document>
+            <paragraph>
+                The
+                <image alt="biohazard" uri="biohazard.png">
+                 symbol is deservedly scary-looking.
+            <substitution_definition name="biohazard">
+                <image alt="biohazard" uri="biohazard.png">
+    """
+
+    default_priority = 220
+    """The Substitutions transform has to be applied very early, before
+    `docutils.tranforms.frontmatter.DocTitle` and others."""
+
+    def apply(self):
+        defs = self.document.substitution_defs
+        for refname, refs in self.document.substitution_refs.items():
+            for ref in refs:
+                if defs.has_key(refname):
+                    ref.parent.replace(ref, defs[refname].get_children())
+                else:
+                    msg = self.document.reporter.error(
+                          'Undefined substitution referenced: "%s".'
+                          % refname, base_node=ref)
+                    msgid = self.document.set_id(msg)
+                    prb = nodes.problematic(
+                          ref.rawsource, ref.rawsource, refid=msgid)
+                    prbid = self.document.set_id(prb)
+                    msg.add_backref(prbid)
+                    ref.parent.replace(ref, prb)
+        self.document.substitution_refs = None  # release replaced references
+
+
+class TargetNotes(Transform):
+
+    """
+    Creates a footnote for each external target in the text, and corresponding
+    footnote references after each reference.
+    """
+
+    default_priority = 540
+    """The TargetNotes transform has to be applied after `IndirectHyperlinks`
+    but before `Footnotes`."""
+
+    def apply(self):
+        notes = {}
+        nodelist = []
+        for target in self.document.external_targets:
+            name = target.get('name')
+            if not name:
+                print >>sys.stderr, 'no name on target: %r' % target
+                continue
+            refs = self.document.refnames.get(name, [])
+            if not refs:
+                continue
+            footnote = self.make_target_footnote(target, refs, notes)
+            if not notes.has_key(target['refuri']):
+                notes[target['refuri']] = footnote
+                nodelist.append(footnote)
+        if len(self.document.anonymous_targets) \
+               == len(self.document.anonymous_refs):
+            for target, ref in zip(self.document.anonymous_targets,
+                                   self.document.anonymous_refs):
+                if target.hasattr('refuri'):
+                    footnote = self.make_target_footnote(target, [ref], notes)
+                    if not notes.has_key(target['refuri']):
+                        notes[target['refuri']] = footnote
+                        nodelist.append(footnote)
+        self.startnode.parent.replace(self.startnode, nodelist)
+
+    def make_target_footnote(self, target, refs, notes):
+        refuri = target['refuri']
+        if notes.has_key(refuri):  # duplicate?
+            footnote = notes[refuri]
+            footnote_name = footnote['name']
+        else:                           # original
+            footnote = nodes.footnote()
+            footnote_id = self.document.set_id(footnote)
+            # Use a colon; they can't be produced inside names by the parser:
+            footnote_name = 'target_note: ' + footnote_id
+            footnote['auto'] = 1
+            footnote['name'] = footnote_name
+            footnote_paragraph = nodes.paragraph()
+            footnote_paragraph += nodes.reference('', refuri, refuri=refuri)
+            footnote += footnote_paragraph
+            self.document.note_autofootnote(footnote)
+            self.document.note_explicit_target(footnote, footnote)
+        for ref in refs:
+            if isinstance(ref, nodes.target):
+                continue
+            refnode = nodes.footnote_reference(
+                refname=footnote_name, auto=1)
+            self.document.note_autofootnote_ref(refnode)
+            self.document.note_footnote_ref(refnode)
+            index = ref.parent.index(ref) + 1
+            reflist = [nodes.Text(' '), refnode]
+            ref.parent.insert(index, reflist)
+        return footnote

lib/python/docutils/transforms/universal.py

+# Authors: David Goodger, Ueli Schlaepfer
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:17 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Transforms needed by most or all documents:
+
+- `Decorations`: Generate a document's header & footer.
+- `Messages`: Placement of system messages stored in
+  `nodes.document.transform_messages`.
+- `TestMessages`: Like `Messages`, used on test runs.
+- `FinalReferences`: Resolve remaining references.
+"""
+
+__docformat__ = 'reStructuredText'
+
+import re
+import sys
+import time
+from docutils import nodes, utils
+from docutils.transforms import TransformError, Transform
+
+
+class Decorations(Transform):
+
+    """
+    Populate a document's decoration element (header, footer).
+    """
+
+    default_priority = 820
+
+    def apply(self):
+        header = self.generate_header()
+        footer = self.generate_footer()
+        if header or footer:
+            decoration = nodes.decoration()
+            decoration += header
+            decoration += footer
+            document = self.document
+            index = document.first_child_not_matching_class(
+                nodes.PreDecorative)
+            if index is None:
+                document += decoration
+            else:
+                document[index:index] = [decoration]
+
+    def generate_header(self):
+        return None
+
+    def generate_footer(self):
+        # @@@ Text is hard-coded for now.
+        # Should be made dynamic (language-dependent).
+        settings = self.document.settings
+        if settings.generator or settings.datestamp or settings.source_link \
+               or settings.source_url:
+            text = []
+            if settings.source_link and settings._source \
+                   or settings.source_url:
+                if settings.source_url:
+                    source = settings.source_url
+                else:
+                    source = utils.relative_path(settings._destination,
+                                                 settings._source)
+                text.extend([
+                    nodes.reference('', 'View document source',
+                                    refuri=source),
+                    nodes.Text('.\n')])
+            if settings.datestamp:
+                datestamp = time.strftime(settings.datestamp, time.gmtime())
+                text.append(nodes.Text('Generated on: ' + datestamp + '.\n'))
+            if settings.generator:
+                text.extend([
+                    nodes.Text('Generated by '),
+                    nodes.reference('', 'Docutils', refuri=
+                                    'http://docutils.sourceforge.net/'),
+                    nodes.Text(' from '),
+                    nodes.reference('', 'reStructuredText', refuri='http://'
+                                    'docutils.sourceforge.net/rst.html'),
+                    nodes.Text(' source.\n')])
+            footer = nodes.footer()
+            footer += nodes.paragraph('', '', *text)
+            return footer
+        else:
+            return None
+
+
+class Messages(Transform):
+
+    """
+    Place any system messages generated after parsing into a dedicated section
+    of the document.
+    """
+
+    default_priority = 860
+
+    def apply(self):
+        unfiltered = self.document.transform_messages
+        threshold = self.document.reporter['writer'].report_level
+        messages = []
+        for msg in unfiltered:
+            if msg['level'] >= threshold and not msg.parent:
+                messages.append(msg)
+        if len(messages) > 0:
+            section = nodes.section(CLASS='system-messages')
+            # @@@ get this from the language module?
+            section += nodes.title('', 'Docutils System Messages')
+            section += messages
+            self.document.transform_messages[:] = []
+            self.document += section
+
+
+class TestMessages(Transform):
+
+    """
+    Append all post-parse system messages to the end of the document.
+    """
+
+    default_priority = 890
+
+    def apply(self):
+        for msg in self.document.transform_messages:
+            if not msg.parent:
+                self.document += msg
+
+
+class FinalChecks(Transform):
+
+    """
+    Perform last-minute checks.
+
+    - Check for dangling references (incl. footnote & citation).
+    """
+
+    default_priority = 840
+
+    def apply(self):
+        visitor = FinalCheckVisitor(self.document)
+        self.document.walk(visitor)
+        if self.document.settings.expose_internals:
+            visitor = InternalAttributeExposer(self.document)
+            self.document.walk(visitor)
+
+
+class FinalCheckVisitor(nodes.SparseNodeVisitor):
+
+    def unknown_visit(self, node):
+        pass
+
+    def visit_reference(self, node):
+        if node.resolved or not node.hasattr('refname'):
+            return
+        refname = node['refname']
+        id = self.document.nameids.get(refname)
+        if id is None:
+            msg = self.document.reporter.error(
+                  'Unknown target name: "%s".' % (node['refname']),
+                  base_node=node)
+            msgid = self.document.set_id(msg)
+            prb = nodes.problematic(
+                  node.rawsource, node.rawsource, refid=msgid)
+            prbid = self.document.set_id(prb)
+            msg.add_backref(prbid)
+            node.parent.replace(node, prb)
+        else:
+            del node['refname']
+            node['refid'] = id
+            self.document.ids[id].referenced = 1
+            node.resolved = 1
+
+    visit_footnote_reference = visit_citation_reference = visit_reference
+
+
+class InternalAttributeExposer(nodes.GenericNodeVisitor):
+
+    def __init__(self, document):
+        nodes.GenericNodeVisitor.__init__(self, document)
+        self.internal_attributes = document.settings.expose_internals
+
+    def default_visit(self, node):
+        for att in self.internal_attributes:
+            value = getattr(node, att, None)
+            if value is not None:
+                node['internal:' + att] = value

lib/python/docutils/urischemes.py

+"""
+`schemes` is a dictionary with lowercase URI addressing schemes as
+keys and descriptions as values. It was compiled from the index at
+http://www.w3.org/Addressing/schemes.html (revised 2001-08-20).
+"""
+
+# Many values are blank and should be filled in with useful descriptions.
+
+schemes = {
+      'about': 'provides information on Navigator',
+      'acap': 'Application Configuration Access Protocol',
+      'addbook': "To add vCard entries to Communicator's Address Book",
+      'afp': 'Apple Filing Protocol',
+      'afs': 'Andrew File System global file names',
+      'aim': 'AOL Instant Messenger',
+      'callto': 'for NetMeeting links',
+      'castanet': 'Castanet Tuner URLs for Netcaster',
+      'chttp': 'cached HTTP supported by RealPlayer',
+      'cid': 'content identifier',
+      'data': ('allows inclusion of small data items as "immediate" data; '
+               'RFC 2397'),
+      'dav': 'Distributed Authoring and Versioning Protocol; RFC 2518',
+      'dns': 'Domain Name System resources',
+      'eid': ('External ID; non-URL data; general escape mechanism to allow '
+              'access to information for applications that are too '
+              'specialized to justify their own schemes'),
+      'fax': ('a connection to a terminal that can handle telefaxes '
+              '(facsimiles); RFC 2806'),
+      'file': 'Host-specific file names',
+      'finger': '',
+      'freenet': '',
+      'ftp': 'File Transfer Protocol',
+      'gopher': 'The Gopher Protocol',
+      'gsm-sms': ('Global System for Mobile Communications Short Message '
+                  'Service'),
+      'h323': 'video (audiovisual) communication on local area networks',
+      'h324': ('video and audio communications over low bitrate connections '
+               'such as POTS modem connections'),
+      'hdl': 'CNRI handle system',
+      'hnews': 'an HTTP-tunneling variant of the NNTP news protocol',
+      'http': 'Hypertext Transfer Protocol',
+      'https': 'HTTP over SSL',
+      'iioploc': 'Internet Inter-ORB Protocol Location?',
+      'ilu': 'Inter-Language Unification',
+      'imap': 'Internet Message Access Protocol',
+      'ior': 'CORBA interoperable object reference',
+      'ipp': 'Internet Printing Protocol',
+      'irc': 'Internet Relay Chat',
+      'jar': 'Java archive',
+      'javascript': ('JavaScript code; evaluates the expression after the '
+                     'colon'),
+      'jdbc': '',
+      'ldap': 'Lightweight Directory Access Protocol',
+      'lifn': '',
+      'livescript': '',
+      'lrq': '',
+      'mailbox': 'Mail folder access',
+      'mailserver': 'Access to data available from mail servers',
+      'mailto': 'Electronic mail address',
+      'md5': '',
+      'mid': 'message identifier',
+      'mocha': '',
+      'modem': ('a connection to a terminal that can handle incoming data '
+                'calls; RFC 2806'),
+      'news': 'USENET news',
+      'nfs': 'Network File System protocol',
+      'nntp': 'USENET news using NNTP access',
+      'opaquelocktoken': '',
+      'phone': '',
+      'pop': 'Post Office Protocol',
+      'pop3': 'Post Office Protocol v3',
+      'printer': '',
+      'prospero': 'Prospero Directory Service',
+      'res': '',
+      'rtsp': 'real time streaming protocol',
+      'rvp': '',
+      'rwhois': '',
+      'rx': 'Remote Execution',
+      'sdp': '',
+      'service': 'service location',
+      'shttp': 'secure hypertext transfer protocol',
+      'sip': 'Session Initiation Protocol',
+      'smb': '',
+      'snews': 'For NNTP postings via SSL',
+      't120': 'real time data conferencing (audiographics)',
+      'tcp': '',
+      'tel': ('a connection to a terminal that handles normal voice '
+              'telephone calls, a voice mailbox or another voice messaging '
+              'system or a service that can be operated using DTMF tones; '
+              'RFC 2806.'),
+      'telephone': 'telephone',
+      'telnet': 'Reference to interactive sessions',
+      'tip': 'Transaction Internet Protocol',
+      'tn3270': 'Interactive 3270 emulation sessions',
+      'tv': '',
+      'urn': 'Uniform Resource Name',
+      'uuid': '',
+      'vemmi': 'versatile multimedia interface',
+      'videotex': '',
+      'view-source': 'displays HTML code that was generated with JavaScript',
+      'wais': 'Wide Area Information Servers',
+      'whodp': '',
+      'whois++': 'Distributed directory service.',
+      'z39.50r': 'Z39.50 Retrieval',
+      'z39.50s': 'Z39.50 Session',}

lib/python/docutils/utils.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:00 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Miscellaneous utilities for the documentation utilities.
+"""
+
+__docformat__ = 'reStructuredText'
+
+import sys
+import os
+import os.path
+from types import StringType, UnicodeType
+from docutils import ApplicationError, DataError
+from docutils import frontend, nodes
+
+
+class SystemMessage(ApplicationError):
+
+    def __init__(self, system_message):
+        Exception.__init__(self, system_message.astext())
+
+
+class Reporter:
+
+    """
+    Info/warning/error reporter and ``system_message`` element generator.
+
+    Five levels of system messages are defined, along with corresponding
+    methods: `debug()`, `info()`, `warning()`, `error()`, and `severe()`.
+
+    There is typically one Reporter object per process.  A Reporter object is
+    instantiated with thresholds for reporting (generating warnings) and
+    halting processing (raising exceptions), a switch to turn debug output on
+    or off, and an I/O stream for warnings.  These are stored in the default
+    reporting category, '' (zero-length string).
+
+    Multiple reporting categories [#]_ may be set, each with its own reporting
+    and halting thresholds, debugging switch, and warning stream
+    (collectively a `ConditionSet`).  Categories are hierarchical dotted-name
+    strings that look like attribute references: 'spam', 'spam.eggs',
+    'neeeow.wum.ping'.  The 'spam' category is the ancestor of
+    'spam.bacon.eggs'.  Unset categories inherit stored conditions from their
+    closest ancestor category that has been set.
+
+    When a system message is generated, the stored conditions from its
+    category (or ancestor if unset) are retrieved.  The system message level
+    is compared to the thresholds stored in the category, and a warning or
+    error is generated as appropriate.  Debug messages are produced iff the
+    stored debug switch is on.  Message output is sent to the stored warning
+    stream.
+
+    The default category is '' (empty string).  By convention, Writers should
+    retrieve reporting conditions from the 'writer' category (which, unless
+    explicitly set, defaults to the conditions of the default category).
+
+    The Reporter class also employs a modified form of the "Observer" pattern
+    [GoF95]_ to track system messages generated.  The `attach_observer` method
+    should be called before parsing, with a bound method or function which
+    accepts system messages.  The observer can be removed with
+    `detach_observer`, and another added in its place.
+
+    .. [#] The concept of "categories" was inspired by the log4j project:
+       http://jakarta.apache.org/log4j/.
+
+    .. [GoF95] Gamma, Helm, Johnson, Vlissides. *Design Patterns: Elements of
+       Reusable Object-Oriented Software*. Addison-Wesley, Reading, MA, USA,
+       1995.
+    """
+
+    levels = 'DEBUG INFO WARNING ERROR SEVERE'.split()
+    """List of names for system message levels, indexed by level."""
+
+    def __init__(self, source, report_level, halt_level, stream=None,
+                 debug=0):
+        """
+        Initialize the `ConditionSet` forthe `Reporter`'s default category.
+
+        :Parameters:
+
+            - `source`: The path to or description of the source data.
+            - `report_level`: The level at or above which warning output will
+              be sent to `stream`.
+            - `halt_level`: The level at or above which `SystemMessage`
+              exceptions will be raised, halting execution.
+            - `debug`: Show debug (level=0) system messages?
+            - `stream`: Where warning output is sent.  Can be file-like (has a
+              ``.write`` method), a string (file name, opened for writing), or
+              `None` (implies `sys.stderr`; default).
+        """
+        self.source = source
+        """The path to or description of the source data."""
+        
+        if stream is None:
+            stream = sys.stderr
+        elif type(stream) in (StringType, UnicodeType):
+            raise NotImplementedError('This should open a file for writing.')
+
+        self.categories = {'': ConditionSet(debug, report_level, halt_level,
+                                            stream)}
+        """Mapping of category names to conditions. Default category is ''."""
+
+        self.observers = []
+        """List of bound methods or functions to call with each system_message
+        created."""
+
+    def set_conditions(self, category, report_level, halt_level,
+                       stream=None, debug=0):
+        if stream is None:
+            stream = sys.stderr
+        self.categories[category] = ConditionSet(debug, report_level,
+                                                 halt_level, stream)
+
+    def unset_conditions(self, category):
+        if category and self.categories.has_key(category):
+            del self.categories[category]
+
+    __delitem__ = unset_conditions
+
+    def get_conditions(self, category):
+        while not self.categories.has_key(category):
+            category = category[:category.rfind('.') + 1][:-1]
+        return self.categories[category]
+
+    __getitem__ = get_conditions
+
+    def attach_observer(self, observer):
+        """
+        The `observer` parameter is a function or bound method which takes one
+        argument, a `nodes.system_message` instance.
+        """
+        self.observers.append(observer)
+
+    def detach_observer(self, observer):
+        self.observers.remove(observer)
+
+    def notify_observers(self, message):
+        for observer in self.observers:
+            observer(message)
+
+    def system_message(self, level, message, *children, **kwargs):
+        """
+        Return a system_message object.
+
+        Raise an exception or generate a warning if appropriate.
+        """
+        attributes = kwargs.copy()
+        category = kwargs.get('category', '')
+        if kwargs.has_key('category'):
+            del attributes['category']
+        if kwargs.has_key('base_node'):
+            source, line = get_source_line(kwargs['base_node'])
+            del attributes['base_node']
+            if source is not None:
+                attributes.setdefault('source', source)
+            if line is not None:
+                attributes.setdefault('line', line)
+        attributes.setdefault('source', self.source)
+        msg = nodes.system_message(message, level=level,
+                                   type=self.levels[level],
+                                   *children, **attributes)
+        debug, report_level, halt_level, stream = self[category].astuple()
+        if level >= report_level or debug and level == 0:
+            if category:
+                print >>stream, msg.astext(), '[%s]' % category
+            else:
+                print >>stream, msg.astext()
+        if level >= halt_level:
+            raise SystemMessage(msg)
+        if level > 0 or debug:
+            self.notify_observers(msg)
+        return msg
+
+    def debug(self, *args, **kwargs):
+        """
+        Level-0, "DEBUG": an internal reporting issue. Typically, there is no
+        effect on the processing. Level-0 system messages are handled
+        separately from the others.
+        """
+        return self.system_message(0, *args, **kwargs)
+
+    def info(self, *args, **kwargs):
+        """
+        Level-1, "INFO": a minor issue that can be ignored. Typically there is
+        no effect on processing, and level-1 system messages are not reported.
+        """
+        return self.system_message(1, *args, **kwargs)
+
+    def warning(self, *args, **kwargs):
+        """
+        Level-2, "WARNING": an issue that should be addressed. If ignored,
+        there may be unpredictable problems with the output.
+        """
+        return self.system_message(2, *args, **kwargs)
+
+    def error(self, *args, **kwargs):
+        """
+        Level-3, "ERROR": an error that should be addressed. If ignored, the
+        output will contain errors.
+        """
+        return self.system_message(3, *args, **kwargs)
+
+    def severe(self, *args, **kwargs):
+        """
+        Level-4, "SEVERE": a severe error that must be addressed. If ignored,
+        the output will contain severe errors. Typically level-4 system
+        messages are turned into exceptions which halt processing.
+        """
+        return self.system_message(4, *args, **kwargs)
+
+
+class ConditionSet:
+
+    """
+    A set of two thresholds (`report_level` & `halt_level`), a switch
+    (`debug`), and an I/O stream (`stream`), corresponding to one `Reporter`
+    category.
+    """
+
+    def __init__(self, debug, report_level, halt_level, stream):
+        self.debug = debug
+        self.report_level = report_level
+        self.halt_level = halt_level
+        self.stream = stream
+
+    def astuple(self):
+        return (self.debug, self.report_level, self.halt_level,
+                self.stream)
+
+
+class ExtensionOptionError(DataError): pass
+class BadOptionError(ExtensionOptionError): pass
+class BadOptionDataError(ExtensionOptionError): pass
+class DuplicateOptionError(ExtensionOptionError): pass
+
+
+def extract_extension_options(field_list, options_spec):
+    """
+    Return a dictionary mapping extension option names to converted values.
+
+    :Parameters:
+        - `field_list`: A flat field list without field arguments, where each
+          field body consists of a single paragraph only.
+        - `options_spec`: Dictionary mapping known option names to a
+          conversion function such as `int` or `float`.
+
+    :Exceptions:
+        - `KeyError` for unknown option names.
+        - `ValueError` for invalid option values (raised by the conversion
+           function).
+        - `DuplicateOptionError` for duplicate options.
+        - `BadOptionError` for invalid fields.
+        - `BadOptionDataError` for invalid option data (missing name,
+          missing data, bad quotes, etc.).
+    """
+    option_list = extract_options(field_list)
+    option_dict = assemble_option_dict(option_list, options_spec)
+    return option_dict
+
+def extract_options(field_list):
+    """
+    Return a list of option (name, value) pairs from field names & bodies.
+
+    :Parameter:
+        `field_list`: A flat field list, where each field name is a single
+        word and each field body consists of a single paragraph only.
+
+    :Exceptions:
+        - `BadOptionError` for invalid fields.
+        - `BadOptionDataError` for invalid option data (missing name,
+          missing data, bad quotes, etc.).
+    """
+    option_list = []
+    for field in field_list:
+        if len(field[0].astext().split()) != 1:
+            raise BadOptionError(
+                'extension option field name may not contain multiple words')
+        name = str(field[0].astext().lower())
+        body = field[1]
+        if len(body) == 0:
+            data = None
+        elif len(body) > 1 or not isinstance(body[0], nodes.paragraph) \
+              or len(body[0]) != 1 or not isinstance(body[0][0], nodes.Text):
+            raise BadOptionDataError(
+                  'extension option field body may contain\n'
+                  'a single paragraph only (option "%s")' % name)
+        else:
+            data = body[0][0].astext()
+        option_list.append((name, data))
+    return option_list
+
+def assemble_option_dict(option_list, options_spec):
+    """
+    Return a mapping of option names to values.
+
+    :Parameters:
+        - `option_list`: A list of (name, value) pairs (the output of
+          `extract_options()`).
+        - `options_spec`: Dictionary mapping known option names to a
+          conversion function such as `int` or `float`.
+
+    :Exceptions:
+        - `KeyError` for unknown option names.
+        - `DuplicateOptionError` for duplicate options.
+        - `ValueError` for invalid option values (raised by conversion
+           function).
+    """
+    options = {}
+    for name, value in option_list:
+        convertor = options_spec[name]       # raises KeyError if unknown
+        if options.has_key(name):
+            raise DuplicateOptionError('duplicate option "%s"' % name)
+        try:
+            options[name] = convertor(value)
+        except (ValueError, TypeError), detail:
+            raise detail.__class__('(option: "%s"; value: %r)\n%s'
+                                   % (name, value, detail))
+    return options
+
+
+class NameValueError(DataError): pass
+
+
+def extract_name_value(line):
+    """
+    Return a list of (name, value) from a line of the form "name=value ...".
+
+    :Exception:
+        `NameValueError` for invalid input (missing name, missing data, bad
+        quotes, etc.).
+    """
+    attlist = []
+    while line:
+        equals = line.find('=')
+        if equals == -1:
+            raise NameValueError('missing "="')
+        attname = line[:equals].strip()
+        if equals == 0 or not attname:
+            raise NameValueError(
+                  'missing attribute name before "="')
+        line = line[equals+1:].lstrip()
+        if not line:
+            raise NameValueError(
+                  'missing value after "%s="' % attname)
+        if line[0] in '\'"':
+            endquote = line.find(line[0], 1)
+            if endquote == -1:
+                raise NameValueError(
+                      'attribute "%s" missing end quote (%s)'
+                      % (attname, line[0]))
+            if len(line) > endquote + 1 and line[endquote + 1].strip():
+                raise NameValueError(
+                      'attribute "%s" end quote (%s) not followed by '
+                      'whitespace' % (attname, line[0]))
+            data = line[1:endquote]
+            line = line[endquote+1:].lstrip()
+        else:
+            space = line.find(' ')
+            if space == -1:
+                data = line
+                line = ''
+            else:
+                data = line[:space]
+                line = line[space+1:].lstrip()
+        attlist.append((attname.lower(), data))
+    return attlist
+
+def normalize_name(name):
+    """Return a case- and whitespace-normalized name."""
+    return ' '.join(name.lower().split())
+
+def new_document(source, settings=None):
+    """
+    Return a new empty document object.
+
+    :Parameters:
+        `source` : string
+            The path to or description of the source text of the document.
+        `settings` : optparse.Values object
+            Runtime settings.  If none provided, a default set will be used.
+    """
+    if settings is None:
+        settings = frontend.OptionParser().get_default_values()
+    reporter = Reporter(source, settings.report_level, settings.halt_level,
+                        settings.warning_stream, settings.debug)
+    document = nodes.document(settings, reporter, source=source)
+    document.note_source(source, -1)
+    return document
+
+def clean_rcs_keywords(paragraph, keyword_substitutions):
+    if len(paragraph) == 1 and isinstance(paragraph[0], nodes.Text):
+        textnode = paragraph[0]
+        for pattern, substitution in keyword_substitutions:
+            match = pattern.match(textnode.data)
+            if match:
+                textnode.data = pattern.sub(substitution, textnode.data)
+                return
+
+def relative_path(source, target):
+    """
+    Build and return a path to `target`, relative to `source`.
+
+    If there is no common prefix, return the absolute path to `target`.
+    """
+    source_parts = os.path.abspath(source or 'dummy_file').split(os.sep)
+    target_parts = os.path.abspath(target).split(os.sep)
+    # Check first 2 parts because '/dir'.split('/') == ['', 'dir']:
+    if source_parts[:2] != target_parts[:2]:
+        # Nothing in common between paths.
+        # Return absolute path, using '/' for URLs:
+        return '/'.join(target_parts)
+    source_parts.reverse()
+    target_parts.reverse()
+    while (source_parts and target_parts
+           and source_parts[-1] == target_parts[-1]):
+        # Remove path components in common:
+        source_parts.pop()
+        target_parts.pop()
+    target_parts.reverse()
+    parts = ['..'] * (len(source_parts) - 1) + target_parts
+    return '/'.join(parts)
+
+def get_source_line(node):
+    """
+    Return the "source" and "line" attributes from the `node` given or from
+    it's closest ancestor.
+    """
+    while node:
+        if node.source or node.line:
+            return node.source, node.line
+        node = node.parent
+    return None, None

lib/python/docutils/writers/__init__.py

+# Authors: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:20 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+This package contains Docutils Writer modules.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+import sys
+import docutils
+from docutils import languages, Component
+from docutils.transforms import universal
+
+
+class Writer(Component):
+
+    """
+    Abstract base class for docutils Writers.
+
+    Each writer module or package must export a subclass also called 'Writer'.
+    Each writer must support all standard node types listed in
+    `docutils.nodes.node_class_names`.
+
+    Call `write()` to process a document.
+    """
+
+    component_type = 'writer'
+
+    document = None
+    """The document to write."""
+
+    language = None
+    """Language module for the document."""
+
+    destination = None
+    """`docutils.io` IO object; where to write the document."""
+
+    def __init__(self):
+        """Initialize the Writer instance."""
+
+    def write(self, document, destination):
+        self.document = document
+        self.language = languages.get_language(
+            document.settings.language_code)
+        self.destination = destination
+        self.translate()
+        output = self.destination.write(self.output)
+        return output
+
+    def translate(self):
+        """
+        Override to do final document tree translation.
+
+        This is usually done with a `docutils.nodes.NodeVisitor` subclass, in
+        combination with a call to `docutils.nodes.Node.walk()` or
+        `docutils.nodes.Node.walkabout()`.  The ``NodeVisitor`` subclass must
+        support all standard elements (listed in
+        `docutils.nodes.node_class_names`) and possibly non-standard elements
+        used by the current Reader as well.
+        """
+        raise NotImplementedError('subclass must override this method')
+
+
+_writer_aliases = {
+      'html': 'html4css1',
+      'pprint': 'pseudoxml',
+      'pformat': 'pseudoxml',
+      'pdf': 'rlpdf',
+      'xml': 'docutils_xml',}
+
+def get_writer_class(writer_name):
+    """Return the Writer class from the `writer_name` module."""
+    writer_name = writer_name.lower()
+    if _writer_aliases.has_key(writer_name):
+        writer_name = _writer_aliases[writer_name]
+    module = __import__(writer_name, globals(), locals())
+    return module.Writer

lib/python/docutils/writers/docutils_xml.py

+# Authors: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:20 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Simple internal document tree Writer, writes Docutils XML.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+import docutils
+from docutils import writers
+
+
+class Writer(writers.Writer):
+
+    supported = ('xml',)
+    """Formats this writer supports."""
+
+    settings_spec = (
+        '"Docutils XML" Writer Options',
+        'Warning: the --newlines and --indents options may adversely affect '
+        'whitespace; use them only for reading convenience.',
+        (('Generate XML with newlines before and after tags.',
+          ['--newlines'], {'action': 'store_true'}),
+         ('Generate XML with indents and newlines.',
+          ['--indents'], {'action': 'store_true'}),
+         ('Omit the XML declaration.  Use with caution.',
+          ['--no-xml-declaration'], {'dest': 'xml_declaration', 'default': 1,
+                                     'action': 'store_false'}),
+         ('Omit the DOCTYPE declaration.',
+          ['--no-doctype'], {'dest': 'doctype_declaration', 'default': 1,
+                             'action': 'store_false'}),))
+
+    output = None
+    """Final translated form of `document`."""
+
+    xml_declaration = '<?xml version="1.0" encoding="%s"?>\n'
+    #xml_stylesheet = '<?xml-stylesheet type="text/xsl" href="%s"?>\n'
+    doctype = (
+        '<!DOCTYPE document PUBLIC'
+        ' "+//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML"'
+        ' "http://docutils.sourceforge.net/spec/docutils.dtd">\n')
+    generator = '<!-- Generated by Docutils %s -->\n'
+
+    def translate(self):
+        settings = self.document.settings
+        indent = newline = ''
+        if settings.newlines:
+            newline = '\n'
+        if settings.indents:
+            newline = '\n'
+            indent = '    '
+        output_prefix = []
+        if settings.xml_declaration:
+            output_prefix.append(
+                self.xml_declaration % settings.output_encoding)
+        if settings.doctype_declaration:
+            output_prefix.append(self.doctype)
+        output_prefix.append(self.generator % docutils.__version__)
+        docnode = self.document.asdom().childNodes[0]
+        self.output = (''.join(output_prefix)
+                       + docnode.toprettyxml(indent, newline))

lib/python/docutils/writers/html4css1.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:20 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Simple HyperText Markup Language document tree Writer.
+
+The output conforms to the HTML 4.01 Transitional DTD and to the Extensible
+HTML version 1.0 Transitional DTD (*almost* strict).  The output contains a
+minimum of formatting information.  A cascading style sheet ("default.css" by
+default) is required for proper viewing with a modern graphical browser.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+import sys
+import os
+import time
+import re
+from types import ListType
+import docutils
+from docutils import nodes, utils, writers, languages
+
+
+class Writer(writers.Writer):
+
+    supported = ('html', 'html4css1', 'xhtml')
+    """Formats this writer supports."""
+
+    settings_spec = (
+        'HTML-Specific Options',
+        None,
+        (('Specify a stylesheet URL, used verbatim.  Default is '
+          '"default.css".  Overridden by --stylesheet-path.',
+          ['--stylesheet'],
+          {'default': 'default.css', 'metavar': '<URL>'}),
+         ('Specify a stylesheet file, relative to the current working '
+          'directory.  The path is adjusted relative to the output HTML '
+          'file.  Overrides --stylesheet.',
+          ['--stylesheet-path'],
+          {'metavar': '<file>'}),
+         ('Link to the stylesheet in the output HTML file.  This is the '
+          'default.',
+          ['--link-stylesheet'],
+          {'dest': 'embed_stylesheet', 'action': 'store_false'}),
+         ('Embed the stylesheet in the output HTML file.  The stylesheet '
+          'file must be accessible during processing (--stylesheet-path is '
+          'recommended).  The stylesheet is embedded inside a comment, so it '
+          'must not contain the text "--" (two hyphens).  Default: link the '
+          'stylesheet, do not embed it.',
+          ['--embed-stylesheet'],
+          {'action': 'store_true'}),
+         ('Format for footnote references: one of "superscript" or '
+          '"brackets".  Default is "superscript".',
+          ['--footnote-references'],
+          {'choices': ['superscript', 'brackets'], 'default': 'superscript',
+           'metavar': '<FORMAT>'}),
+         ('Remove extra vertical whitespace between items of bullet lists '
+          'and enumerated lists, when list items are "simple" (i.e., all '
+          'items each contain one paragraph and/or one "simple" sublist '
+          'only).  Default: enabled.',
+          ['--compact-lists'],
+          {'default': 1, 'action': 'store_true'}),
+         ('Disable compact simple bullet and enumerated lists.',
+          ['--no-compact-lists'],
+          {'dest': 'compact_lists', 'action': 'store_false'}),))
+
+    relative_path_settings = ('stylesheet_path',)
+
+    output = None
+    """Final translated form of `document`."""
+
+    def __init__(self):
+        writers.Writer.__init__(self)
+        self.translator_class = HTMLTranslator
+
+    def translate(self):
+        visitor = self.translator_class(self.document)
+        self.document.walkabout(visitor)
+        self.output = visitor.astext()
+        self.head_prefix = visitor.head_prefix
+        self.stylesheet = visitor.stylesheet
+        self.head = visitor.head
+        self.body_prefix = visitor.body_prefix
+        self.body_pre_docinfo = visitor.body_pre_docinfo
+        self.docinfo = visitor.docinfo
+        self.body = visitor.body
+        self.body_suffix = visitor.body_suffix
+
+
+class HTMLTranslator(nodes.NodeVisitor):
+
+    """
+    This HTML writer has been optimized to produce visually compact
+    lists (less vertical whitespace).  HTML's mixed content models
+    allow list items to contain "<li><p>body elements</p></li>" or
+    "<li>just text</li>" or even "<li>text<p>and body
+    elements</p>combined</li>", each with different effects.  It would
+    be best to stick with strict body elements in list items, but they
+    affect vertical spacing in browsers (although they really
+    shouldn't).
+
+    Here is an outline of the optimization:
+
+    - Check for and omit <p> tags in "simple" lists: list items
+      contain either a single paragraph, a nested simple list, or a
+      paragraph followed by a nested simple list.  This means that
+      this list can be compact:
+
+          - Item 1.
+          - Item 2.
+
+      But this list cannot be compact:
+
+          - Item 1.
+
+            This second paragraph forces space between list items.
+
+          - Item 2.
+
+    - In non-list contexts, omit <p> tags on a paragraph if that
+      paragraph is the only child of its parent (footnotes & citations
+      are allowed a label first).
+
+    - Regardless of the above, in definitions, table cells, field bodies,
+      option descriptions, and list items, mark the first child with
+      'class="first"' and the last child with 'class="last"'.  The stylesheet
+      sets the margins (top & bottom respecively) to 0 for these elements.
+
+    The ``no_compact_lists`` setting (``--no-compact-lists`` command-line
+    option) disables list whitespace optimization.
+    """
+
+    xml_declaration = '<?xml version="1.0" encoding="%s" ?>\n'
+    doctype = ('<!DOCTYPE html' 
+               ' PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"'
+               ' "http://www.w3.org/TR/xhtml1/DTD/'
+               'xhtml1-transitional.dtd">\n')
+    html_head = ('<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="%s" '
+                 'lang="%s">\n<head>\n')
+    content_type = ('<meta http-equiv="Content-Type" content="text/html; '
+                    'charset=%s" />\n')
+    generator = ('<meta name="generator" content="Docutils %s: '
+                 'http://docutils.sourceforge.net/" />\n')
+    stylesheet_link = '<link rel="stylesheet" href="%s" type="text/css" />\n'
+    embedded_stylesheet = '<style type="text/css"><!--\n\n%s\n--></style>\n'
+    named_tags = {'a': 1, 'applet': 1, 'form': 1, 'frame': 1, 'iframe': 1,
+                  'img': 1, 'map': 1}
+    words_and_spaces = re.compile(r'\S+| +|\n')
+
+    def __init__(self, document):
+        nodes.NodeVisitor.__init__(self, document)
+        self.settings = settings = document.settings
+        lcode = settings.language_code
+        self.language = languages.get_language(lcode)
+        self.head_prefix = [
+              self.xml_declaration % settings.output_encoding,
+              self.doctype,
+              self.html_head % (lcode, lcode),
+              self.content_type % settings.output_encoding,
+              self.generator % docutils.__version__]
+        self.head = []
+        if settings.embed_stylesheet:
+            stylesheet = self.get_stylesheet_reference(os.getcwd())
+            stylesheet_text = open(stylesheet).read()
+            self.stylesheet = [self.embedded_stylesheet % stylesheet_text]
+        else:
+            stylesheet = self.get_stylesheet_reference()
+            if stylesheet:
+                self.stylesheet = [self.stylesheet_link % stylesheet]
+            else:
+                self.stylesheet = []
+        self.body_prefix = ['</head>\n<body>\n']
+        self.body_pre_docinfo = []
+        self.docinfo = []
+        self.body = []
+        self.body_suffix = ['</body>\n</html>\n']
+        self.section_level = 0
+        self.context = []
+        self.topic_class = ''
+        self.colspecs = []
+        self.compact_p = 1
+        self.compact_simple = None
+        self.in_docinfo = None
+
+    def get_stylesheet_reference(self, relative_to=None):
+        settings = self.settings
+        if settings.stylesheet_path:
+            if relative_to == None:
+                relative_to = settings._destination
+            return utils.relative_path(relative_to, settings.stylesheet_path)
+        else:
+            return settings.stylesheet
+
+    def astext(self):
+        return ''.join(self.head_prefix + self.head + self.stylesheet
+                       + self.body_prefix + self.body_pre_docinfo
+                       + self.docinfo + self.body + self.body_suffix)
+
+    def encode(self, text):
+        """Encode special characters in `text` & return."""
+        # @@@ A codec to do these and all other HTML entities would be nice.
+        text = text.replace("&", "&amp;")
+        text = text.replace("<", "&lt;")
+        text = text.replace('"', "&quot;")
+        text = text.replace(">", "&gt;")
+        text = text.replace("@", "&#64;") # may thwart some address harvesters
+        return text
+
+    def attval(self, text,
+               whitespace=re.compile('[\n\r\t\v\f]')):
+        """Cleanse, HTML encode, and return attribute value text."""
+        return self.encode(whitespace.sub(' ', text))
+
+    def starttag(self, node, tagname, suffix='\n', infix='', **attributes):
+        """
+        Construct and return a start tag given a node (id & class attributes
+        are extracted), tag name, and optional attributes.
+        """
+        tagname = tagname.lower()
+        atts = {}
+        for (name, value) in attributes.items():
+            atts[name.lower()] = value
+        for att in ('class',):          # append to node attribute
+            if node.has_key(att) or atts.has_key(att):
+                atts[att] = \
+                      (node.get(att, '') + ' ' + atts.get(att, '')).strip()
+        for att in ('id',):             # node attribute overrides
+            if node.has_key(att):
+                atts[att] = node[att]
+        if atts.has_key('id') and self.named_tags.has_key(tagname):
+            atts['name'] = atts['id']   # for compatibility with old browsers
+        attlist = atts.items()
+        attlist.sort()
+        parts = [tagname]
+        for name, value in attlist:
+            if value is None:           # boolean attribute
+                # According to the HTML spec, ``<element boolean>`` is good,
+                # ``<element boolean="boolean">`` is bad.
+                # (But the XHTML (XML) spec says the opposite.  <sigh>)
+                parts.append(name.lower())
+            elif isinstance(value, ListType):
+                values = [str(v) for v in value]
+                parts.append('%s="%s"' % (name.lower(),
+                                          self.attval(' '.join(values))))
+            else:
+                parts.append('%s="%s"' % (name.lower(),
+                                          self.attval(str(value))))
+        return '<%s%s>%s' % (' '.join(parts), infix, suffix)
+
+    def emptytag(self, node, tagname, suffix='\n', **attributes):
+        """Construct and return an XML-compatible empty tag."""
+        return self.starttag(node, tagname, suffix, infix=' /', **attributes)
+
+    def visit_Text(self, node):
+        self.body.append(self.encode(node.astext()))
+
+    def depart_Text(self, node):
+        pass
+
+    def visit_address(self, node):
+        self.visit_docinfo_item(node, 'address', meta=None)
+        self.body.append(self.starttag(node, 'pre', CLASS='address'))
+
+    def depart_address(self, node):
+        self.body.append('\n</pre>\n')
+        self.depart_docinfo_item()
+
+    def visit_admonition(self, node, name):
+        self.body.append(self.starttag(node, 'div', CLASS=name))
+        self.body.append('<p class="admonition-title">'
+                         + self.language.labels[name] + '</p>\n')
+
+    def depart_admonition(self):
+        self.body.append('</div>\n')
+
+    def visit_attention(self, node):
+        self.visit_admonition(node, 'attention')
+
+    def depart_attention(self, node):
+        self.depart_admonition()
+
+    def visit_author(self, node):
+        self.visit_docinfo_item(node, 'author')
+
+    def depart_author(self, node):
+        self.depart_docinfo_item()
+
+    def visit_authors(self, node):
+        pass
+
+    def depart_authors(self, node):
+        pass
+
+    def visit_block_quote(self, node):
+        self.body.append(self.starttag(node, 'blockquote'))
+
+    def depart_block_quote(self, node):
+        self.body.append('</blockquote>\n')
+
+    def check_simple_list(self, node):
+        """Check for a simple list that can be rendered compactly."""
+        visitor = SimpleListChecker(self.document)
+        try:
+            node.walk(visitor)
+        except nodes.NodeFound:
+            return None
+        else:
+            return 1
+
+    def visit_bullet_list(self, node):
+        atts = {}
+        old_compact_simple = self.compact_simple
+        self.context.append((self.compact_simple, self.compact_p))
+        self.compact_p = None
+        self.compact_simple = (self.settings.compact_lists and
+                               (self.compact_simple
+                                or self.topic_class == 'contents'
+                                or self.check_simple_list(node)))
+        if self.compact_simple and not old_compact_simple:
+            atts['class'] = 'simple'
+        self.body.append(self.starttag(node, 'ul', **atts))
+
+    def depart_bullet_list(self, node):
+        self.compact_simple, self.compact_p = self.context.pop()
+        self.body.append('</ul>\n')
+
+    def visit_caption(self, node):
+        self.body.append(self.starttag(node, 'p', '', CLASS='caption'))
+
+    def depart_caption(self, node):
+        self.body.append('</p>\n')
+
+    def visit_caution(self, node):
+        self.visit_admonition(node, 'caution')
+
+    def depart_caution(self, node):
+        self.depart_admonition()
+
+    def visit_citation(self, node):
+        self.body.append(self.starttag(node, 'table', CLASS='citation',
+                                       frame="void", rules="none"))
+        self.body.append('<colgroup><col class="label" /><col /></colgroup>\n'
+                         '<col />\n'
+                         '<tbody valign="top">\n'
+                         '<tr>')
+        self.footnote_backrefs(node)
+
+    def depart_citation(self, node):
+        self.body.append('</td></tr>\n'
+                         '</tbody>\n</table>\n')
+
+    def visit_citation_reference(self, node):
+        href = ''
+        if node.has_key('refid'):
+            href = '#' + node['refid']
+        elif node.has_key('refname'):
+            href = '#' + self.document.nameids[node['refname']]
+        self.body.append(self.starttag(node, 'a', '[', href=href,
+                                       CLASS='citation-reference'))
+
+    def depart_citation_reference(self, node):
+        self.body.append(']</a>')
+
+    def visit_classifier(self, node):
+        self.body.append(' <span class="classifier-delimiter">:</span> ')
+        self.body.append(self.starttag(node, 'span', '', CLASS='classifier'))
+
+    def depart_classifier(self, node):
+        self.body.append('</span>')
+
+    def visit_colspec(self, node):
+        self.colspecs.append(node)
+
+    def depart_colspec(self, node):
+        pass
+
+    def write_colspecs(self):
+        width = 0
+        for node in self.colspecs:
+            width += node['colwidth']
+        for node in self.colspecs:
+            colwidth = int(node['colwidth'] * 100.0 / width + 0.5)
+            self.body.append(self.emptytag(node, 'col',
+                                           width='%i%%' % colwidth))
+        self.colspecs = []
+
+    def visit_comment(self, node,
+                      sub=re.compile('-(?=-)').sub):
+        """Escape double-dashes in comment text."""
+        self.body.append('<!-- %s -->\n' % sub('- ', node.astext()))
+        # Content already processed:
+        raise nodes.SkipNode
+
+    def visit_contact(self, node):
+        self.visit_docinfo_item(node, 'contact', meta=None)
+
+    def depart_contact(self, node):
+        self.depart_docinfo_item()
+
+    def visit_copyright(self, node):
+        self.visit_docinfo_item(node, 'copyright')
+
+    def depart_copyright(self, node):
+        self.depart_docinfo_item()
+
+    def visit_danger(self, node):
+        self.visit_admonition(node, 'danger')
+
+    def depart_danger(self, node):
+        self.depart_admonition()
+
+    def visit_date(self, node):
+        self.visit_docinfo_item(node, 'date')
+
+    def depart_date(self, node):
+        self.depart_docinfo_item()
+
+    def visit_decoration(self, node):
+        pass
+
+    def depart_decoration(self, node):
+        pass
+
+    def visit_definition(self, node):
+        self.body.append('</dt>\n')
+        self.body.append(self.starttag(node, 'dd', ''))
+        if len(node):
+            node[0].set_class('first')
+            node[-1].set_class('last')
+
+    def depart_definition(self, node):
+        self.body.append('</dd>\n')
+
+    def visit_definition_list(self, node):
+        self.body.append(self.starttag(node, 'dl'))
+
+    def depart_definition_list(self, node):
+        self.body.append('</dl>\n')
+
+    def visit_definition_list_item(self, node):
+        pass
+
+    def depart_definition_list_item(self, node):
+        pass
+
+    def visit_description(self, node):
+        self.body.append(self.starttag(node, 'td', ''))
+        if len(node):
+            node[0].set_class('first')
+            node[-1].set_class('last')
+
+    def depart_description(self, node):
+        self.body.append('</td>')
+
+    def visit_docinfo(self, node):
+        self.context.append(len(self.body))
+        self.body.append(self.starttag(node, 'table', CLASS='docinfo',
+                                       frame="void", rules="none"))
+        self.body.append('<col class="docinfo-name" />\n'
+                         '<col class="docinfo-content" />\n'
+                         '<tbody valign="top">\n')
+        self.in_docinfo = 1
+
+    def depart_docinfo(self, node):
+        self.body.append('</tbody>\n</table>\n')
+        self.in_docinfo = None
+        start = self.context.pop()
+        self.body_pre_docinfo = self.body[:start]
+        self.docinfo = self.body[start:]
+        self.body = []
+
+    def visit_docinfo_item(self, node, name, meta=1):
+        if meta:
+            self.head.append('<meta name="%s" content="%s" />\n'
+                             % (name, self.attval(node.astext())))
+        self.body.append(self.starttag(node, 'tr', ''))
+        self.body.append('<th class="docinfo-name">%s:</th>\n<td>'
+                         % self.language.labels[name])
+        if len(node):
+            if isinstance(node[0], nodes.Element):
+                node[0].set_class('first')
+            if isinstance(node[0], nodes.Element):
+                node[-1].set_class('last')
+
+    def depart_docinfo_item(self):
+        self.body.append('</td></tr>\n')
+
+    def visit_doctest_block(self, node):
+        self.body.append(self.starttag(node, 'pre', CLASS='doctest-block'))
+
+    def depart_doctest_block(self, node):
+        self.body.append('\n</pre>\n')
+
+    def visit_document(self, node):
+        self.body.append(self.starttag(node, 'div', CLASS='document'))
+
+    def depart_document(self, node):
+        self.body.append('</div>\n')
+
+    def visit_emphasis(self, node):
+        self.body.append('<em>')
+
+    def depart_emphasis(self, node):
+        self.body.append('</em>')
+
+    def visit_entry(self, node):
+        if isinstance(node.parent.parent, nodes.thead):
+            tagname = 'th'
+        else:
+            tagname = 'td'
+        atts = {}
+        if node.has_key('morerows'):
+            atts['rowspan'] = node['morerows'] + 1
+        if node.has_key('morecols'):
+            atts['colspan'] = node['morecols'] + 1
+        self.body.append(self.starttag(node, tagname, '', **atts))
+        self.context.append('</%s>\n' % tagname.lower())
+        if len(node) == 0:              # empty cell
+            self.body.append('&nbsp;')
+        else:
+            node[0].set_class('first')
+            node[-1].set_class('last')
+
+    def depart_entry(self, node):
+        self.body.append(self.context.pop())
+
+    def visit_enumerated_list(self, node):
+        """
+        The 'start' attribute does not conform to HTML 4.01's strict.dtd, but
+        CSS1 doesn't help. CSS2 isn't widely enough supported yet to be
+        usable.
+        """
+        atts = {}
+        if node.has_key('start'):
+            atts['start'] = node['start']
+        if node.has_key('enumtype'):
+            atts['class'] = node['enumtype']
+        # @@@ To do: prefix, suffix. How? Change prefix/suffix to a
+        # single "format" attribute? Use CSS2?
+        old_compact_simple = self.compact_simple
+        self.context.append((self.compact_simple, self.compact_p))
+        self.compact_p = None
+        self.compact_simple = (self.settings.compact_lists and
+                               (self.compact_simple
+                                or self.topic_class == 'contents'
+                                or self.check_simple_list(node)))
+        if self.compact_simple and not old_compact_simple:
+            atts['class'] = (atts.get('class', '') + ' simple').strip()
+        self.body.append(self.starttag(node, 'ol', **atts))
+
+    def depart_enumerated_list(self, node):
+        self.compact_simple, self.compact_p = self.context.pop()
+        self.body.append('</ol>\n')
+
+    def visit_error(self, node):
+        self.visit_admonition(node, 'error')
+
+    def depart_error(self, node):
+        self.depart_admonition()
+
+    def visit_field(self, node):
+        self.body.append(self.starttag(node, 'tr', '', CLASS='field'))
+
+    def depart_field(self, node):
+        self.body.append('</tr>\n')
+
+    def visit_field_body(self, node):
+        self.body.append(self.starttag(node, 'td', '', CLASS='field-body'))
+        if len(node):
+            node[0].set_class('first')
+            node[-1].set_class('last')
+
+    def depart_field_body(self, node):
+        self.body.append('</td>\n')
+
+    def visit_field_list(self, node):
+        self.body.append(self.starttag(node, 'table', frame='void',
+                                       rules='none', CLASS='field-list'))
+        self.body.append('<col class="field-name" />\n'
+                         '<col class="field-body" />\n'
+                         '<tbody valign="top">\n')
+
+    def depart_field_list(self, node):
+        self.body.append('</tbody>\n</table>\n')
+
+    def visit_field_name(self, node):
+        atts = {}
+        if self.in_docinfo:
+            atts['class'] = 'docinfo-name'
+        else:
+            atts['class'] = 'field-name'
+        if len(node.astext()) > 14:
+            atts['colspan'] = 2
+            self.context.append('</tr>\n<tr><td>&nbsp;</td>')
+        else:
+            self.context.append('')
+        self.body.append(self.starttag(node, 'th', '', **atts))
+
+    def depart_field_name(self, node):
+        self.body.append(':</th>')
+        self.body.append(self.context.pop())
+
+    def visit_figure(self, node):
+        self.body.append(self.starttag(node, 'div', CLASS='figure'))
+
+    def depart_figure(self, node):
+        self.body.append('</div>\n')
+
+    def visit_footer(self, node):
+        self.context.append(len(self.body))
+
+    def depart_footer(self, node):
+        start = self.context.pop()
+        footer = (['<hr class="footer"/>\n',
+                   self.starttag(node, 'div', CLASS='footer')]
+                  + self.body[start:] + ['</div>\n'])
+        self.body_suffix[:0] = footer
+        del self.body[start:]
+
+    def visit_footnote(self, node):
+        self.body.append(self.starttag(node, 'table', CLASS='footnote',
+                                       frame="void", rules="none"))
+        self.body.append('<colgroup><col class="label" /><col /></colgroup>\n'
+                         '<tbody valign="top">\n'
+                         '<tr>')
+        self.footnote_backrefs(node)
+
+    def footnote_backrefs(self, node):
+        if self.settings.footnote_backlinks and node.hasattr('backrefs'):
+            backrefs = node['backrefs']
+            if len(backrefs) == 1:
+                self.context.append('')
+                self.context.append('<a class="fn-backref" href="#%s" '
+                                    'name="%s">' % (backrefs[0], node['id']))
+            else:
+                i = 1
+                backlinks = []
+                for backref in backrefs:
+                    backlinks.append('<a class="fn-backref" href="#%s">%s</a>'
+                                     % (backref, i))
+                    i += 1
+                self.context.append('<em>(%s)</em> ' % ', '.join(backlinks))
+                self.context.append('<a name="%s">' % node['id'])
+        else:
+            self.context.append('')
+            self.context.append('<a name="%s">' % node['id'])
+
+    def depart_footnote(self, node):
+        self.body.append('</td></tr>\n'
+                         '</tbody>\n</table>\n')
+
+    def visit_footnote_reference(self, node):
+        href = ''
+        if node.has_key('refid'):
+            href = '#' + node['refid']
+        elif node.has_key('refname'):
+            href = '#' + self.document.nameids[node['refname']]
+        format = self.settings.footnote_references
+        if format == 'brackets':
+            suffix = '['
+            self.context.append(']')
+        elif format == 'superscript':
+            suffix = '<sup>'
+            self.context.append('</sup>')
+        else:                           # shouldn't happen
+            suffix = '???'
+            self.content.append('???')
+        self.body.append(self.starttag(node, 'a', suffix, href=href,
+                                       CLASS='footnote-reference'))
+
+    def depart_footnote_reference(self, node):
+        self.body.append(self.context.pop() + '</a>')
+
+    def visit_generated(self, node):
+        pass
+
+    def depart_generated(self, node):
+        pass
+
+    def visit_header(self, node):
+        self.context.append(len(self.body))
+
+    def depart_header(self, node):
+        start = self.context.pop()
+        self.body_prefix.append(self.starttag(node, 'div', CLASS='header'))
+        self.body_prefix.extend(self.body[start:])
+        self.body_prefix.append('<hr />\n</div>\n')
+        del self.body[start:]
+
+    def visit_hint(self, node):
+        self.visit_admonition(node, 'hint')
+
+    def depart_hint(self, node):
+        self.depart_admonition()
+
+    def visit_image(self, node):
+        atts = node.attributes.copy()
+        atts['src'] = atts['uri']
+        del atts['uri']
+        if not atts.has_key('alt'):
+            atts['alt'] = atts['src']
+        if isinstance(node.parent, nodes.TextElement):
+            self.context.append('')
+        else:
+            self.body.append('<p>')
+            self.context.append('</p>\n')
+        self.body.append(self.emptytag(node, 'img', '', **atts))
+
+    def depart_image(self, node):
+        self.body.append(self.context.pop())
+
+    def visit_important(self, node):
+        self.visit_admonition(node, 'important')
+
+    def depart_important(self, node):
+        self.depart_admonition()
+
+    def visit_label(self, node):
+        self.body.append(self.starttag(node, 'td', '%s[' % self.context.pop(),
+                                       CLASS='label'))
+
+    def depart_label(self, node):
+        self.body.append(']</a></td><td>%s' % self.context.pop())
+
+    def visit_legend(self, node):
+        self.body.append(self.starttag(node, 'div', CLASS='legend'))
+
+    def depart_legend(self, node):
+        self.body.append('</div>\n')
+
+    def visit_line_block(self, node):
+        self.body.append(self.starttag(node, 'pre', CLASS='line-block'))
+
+    def depart_line_block(self, node):
+        self.body.append('\n</pre>\n')
+
+    def visit_list_item(self, node):
+        self.body.append(self.starttag(node, 'li', ''))
+        if len(node):
+            node[0].set_class('first')
+
+    def depart_list_item(self, node):
+        self.body.append('</li>\n')
+
+    def visit_literal(self, node):
+        """Process text to prevent tokens from wrapping."""
+        self.body.append(self.starttag(node, 'tt', '', CLASS='literal'))
+        text = node.astext()
+        for token in self.words_and_spaces.findall(text):
+            if token.strip():
+                # Protect text like "--an-option" from bad line wrapping:
+                self.body.append('<span class="pre">%s</span>'
+                                 % self.encode(token))
+            elif token in ('\n', ' '):
+                # Allow breaks at whitespace:
+                self.body.append(token)
+            else:
+                # Protect runs of multiple spaces; the last space can wrap:
+                self.body.append('&nbsp;' * (len(token) - 1) + ' ')
+        self.body.append('</tt>')
+        # Content already processed:
+        raise nodes.SkipNode
+
+    def visit_literal_block(self, node):
+        self.body.append(self.starttag(node, 'pre', CLASS='literal-block'))
+
+    def depart_literal_block(self, node):
+        self.body.append('\n</pre>\n')
+
+    def visit_meta(self, node):
+        self.head.append(self.emptytag(node, 'meta', **node.attributes))
+
+    def depart_meta(self, node):
+        pass
+
+    def visit_note(self, node):
+        self.visit_admonition(node, 'note')
+
+    def depart_note(self, node):
+        self.depart_admonition()
+
+    def visit_option(self, node):
+        if self.context[-1]:
+            self.body.append(', ')
+
+    def depart_option(self, node):
+        self.context[-1] += 1
+
+    def visit_option_argument(self, node):
+        self.body.append(node.get('delimiter', ' '))
+        self.body.append(self.starttag(node, 'var', ''))
+
+    def depart_option_argument(self, node):
+        self.body.append('</var>')
+
+    def visit_option_group(self, node):
+        atts = {}
+        if len(node.astext()) > 14:
+            atts['colspan'] = 2
+            self.context.append('</tr>\n<tr><td>&nbsp;</td>')
+        else:
+            self.context.append('')
+        self.body.append(self.starttag(node, 'td', **atts))
+        self.body.append('<kbd>')
+        self.context.append(0)          # count number of options
+
+    def depart_option_group(self, node):
+        self.context.pop()
+        self.body.append('</kbd></td>\n')
+        self.body.append(self.context.pop())
+
+    def visit_option_list(self, node):
+        self.body.append(
+              self.starttag(node, 'table', CLASS='option-list',
+                            frame="void", rules="none"))
+        self.body.append('<col class="option" />\n'
+                         '<col class="description" />\n'
+                         '<tbody valign="top">\n')
+
+    def depart_option_list(self, node):
+        self.body.append('</tbody>\n</table>\n')
+
+    def visit_option_list_item(self, node):
+        self.body.append(self.starttag(node, 'tr', ''))
+
+    def depart_option_list_item(self, node):
+        self.body.append('</tr>\n')
+
+    def visit_option_string(self, node):
+        self.body.append(self.starttag(node, 'span', '', CLASS='option'))
+
+    def depart_option_string(self, node):
+        self.body.append('</span>')
+
+    def visit_organization(self, node):
+        self.visit_docinfo_item(node, 'organization')
+
+    def depart_organization(self, node):
+        self.depart_docinfo_item()
+
+    def visit_paragraph(self, node):
+        # Omit <p> tags if this is an only child and optimizable.
+        if (self.compact_simple or
+            self.compact_p and (len(node.parent) == 1 or
+                                len(node.parent) == 2 and
+                                isinstance(node.parent[0], nodes.label))):
+            self.context.append('')
+        else:
+            self.body.append(self.starttag(node, 'p', ''))
+            self.context.append('</p>\n')
+
+    def depart_paragraph(self, node):
+        self.body.append(self.context.pop())
+
+    def visit_problematic(self, node):
+        if node.hasattr('refid'):
+            self.body.append('<a href="#%s" name="%s">' % (node['refid'],
+                                                           node['id']))
+            self.context.append('</a>')
+        else:
+            self.context.append('')
+        self.body.append(self.starttag(node, 'span', '', CLASS='problematic'))
+
+    def depart_problematic(self, node):
+        self.body.append('</span>')
+        self.body.append(self.context.pop())
+
+    def visit_raw(self, node):
+        if node.get('format') == 'html':
+            self.body.append(node.astext())
+        # Keep non-HTML raw text out of output:
+        raise nodes.SkipNode
+
+    def visit_reference(self, node):
+        if node.has_key('refuri'):
+            href = node['refuri']
+        elif node.has_key('refid'):
+            href = '#' + node['refid']
+        elif node.has_key('refname'):
+            href = '#' + self.document.nameids[node['refname']]
+        self.body.append(self.starttag(node, 'a', '', href=href,
+                                       CLASS='reference'))
+
+    def depart_reference(self, node):
+        self.body.append('</a>')
+
+    def visit_revision(self, node):
+        self.visit_docinfo_item(node, 'revision', meta=None)
+
+    def depart_revision(self, node):
+        self.depart_docinfo_item()
+
+    def visit_row(self, node):
+        self.body.append(self.starttag(node, 'tr', ''))
+
+    def depart_row(self, node):
+        self.body.append('</tr>\n')
+
+    def visit_section(self, node):
+        self.section_level += 1
+        self.body.append(self.starttag(node, 'div', CLASS='section'))
+
+    def depart_section(self, node):
+        self.section_level -= 1
+        self.body.append('</div>\n')
+
+    def visit_status(self, node):
+        self.visit_docinfo_item(node, 'status', meta=None)
+
+    def depart_status(self, node):
+        self.depart_docinfo_item()
+
+    def visit_strong(self, node):
+        self.body.append('<strong>')
+
+    def depart_strong(self, node):
+        self.body.append('</strong>')
+
+    def visit_substitution_definition(self, node):
+        """Internal only."""
+        raise nodes.SkipNode
+
+    def visit_substitution_reference(self, node):
+        self.unimplemented_visit(node)
+
+    def visit_subtitle(self, node):
+        self.body.append(self.starttag(node, 'h2', '', CLASS='subtitle'))
+
+    def depart_subtitle(self, node):
+        self.body.append('</h2>\n')
+
+    def visit_system_message(self, node):
+        if node['level'] < self.document.reporter['writer'].report_level:
+            # Level is too low to display:
+            raise nodes.SkipNode
+        self.body.append(self.starttag(node, 'div', CLASS='system-message'))
+        self.body.append('<p class="system-message-title">')
+        attr = {}
+        backref_text = ''
+        if node.hasattr('id'):
+            attr['name'] = node['id']
+        if node.hasattr('backrefs'):
+            backrefs = node['backrefs']
+            if len(backrefs) == 1:
+                backref_text = ('; <em><a href="#%s">backlink</a></em>'
+                                % backrefs[0])
+            else:
+                i = 1
+                backlinks = []
+                for backref in backrefs:
+                    backlinks.append('<a href="#%s">%s</a>' % (backref, i))
+                    i += 1
+                backref_text = ('; <em>backlinks: %s</em>'
+                                % ', '.join(backlinks))
+        if node.hasattr('line'):
+            line = ', line %s' % node['line']
+        else:
+            line = ''
+        if attr:
+            a_start = self.starttag({}, 'a', '', **attr)
+            a_end = '</a>'
+        else:
+            a_start = a_end = ''
+        self.body.append('System Message: %s%s/%s%s (<tt>%s</tt>%s)%s</p>\n'
+                         % (a_start, node['type'], node['level'], a_end,
+                            node['source'], line, backref_text))
+
+    def depart_system_message(self, node):
+        self.body.append('</div>\n')
+
+    def visit_table(self, node):
+        self.body.append(
+              self.starttag(node, 'table', CLASS="table",
+                            frame='border', rules='all'))
+
+    def depart_table(self, node):
+        self.body.append('</table>\n')
+
+    def visit_target(self, node):
+        if not (node.has_key('refuri') or node.has_key('refid')
+                or node.has_key('refname')):
+            self.body.append(self.starttag(node, 'a', '', CLASS='target'))
+            self.context.append('</a>')
+        else:
+            self.context.append('')
+
+    def depart_target(self, node):
+        self.body.append(self.context.pop())
+
+    def visit_tbody(self, node):
+        self.write_colspecs()
+        self.body.append(self.context.pop()) # '</colgroup>\n' or ''
+        self.body.append(self.starttag(node, 'tbody', valign='top'))
+
+    def depart_tbody(self, node):
+        self.body.append('</tbody>\n')
+
+    def visit_term(self, node):
+        self.body.append(self.starttag(node, 'dt', ''))
+
+    def depart_term(self, node):
+        """
+        Leave the end tag to `self.visit_definition()`, in case there's a
+        classifier.
+        """
+        pass
+
+    def visit_tgroup(self, node):
+        # Mozilla needs <colgroup>:
+        self.body.append(self.starttag(node, 'colgroup'))
+        # Appended by thead or tbody:
+        self.context.append('</colgroup>\n')
+
+    def depart_tgroup(self, node):
+        pass
+
+    def visit_thead(self, node):
+        self.write_colspecs()
+        self.body.append(self.context.pop()) # '</colgroup>\n'
+        # There may or may not be a <thead>; this is for <tbody> to use:
+        self.context.append('')
+        self.body.append(self.starttag(node, 'thead', valign='bottom'))
+
+    def depart_thead(self, node):
+        self.body.append('</thead>\n')
+
+    def visit_tip(self, node):
+        self.visit_admonition(node, 'tip')
+
+    def depart_tip(self, node):
+        self.depart_admonition()
+
+    def visit_title(self, node):
+        """Only 6 section levels are supported by HTML."""
+        if isinstance(node.parent, nodes.topic):
+            self.body.append(
+                  self.starttag(node, 'p', '', CLASS='topic-title'))
+            if node.parent.hasattr('id'):
+                self.body.append(
+                    self.starttag({}, 'a', '', name=node.parent['id']))
+                self.context.append('</a></p>\n')
+            else:
+                self.context.append('</p>\n')
+        elif self.section_level == 0:
+            # document title
+            self.head.append('<title>%s</title>\n'
+                             % self.encode(node.astext()))
+            self.body.append(self.starttag(node, 'h1', '', CLASS='title'))
+            self.context.append('</h1>\n')
+        else:
+            self.body.append(
+                  self.starttag(node, 'h%s' % self.section_level, ''))
+            atts = {}
+            if node.parent.hasattr('id'):
+                atts['name'] = node.parent['id']
+            if node.hasattr('refid'):
+                atts['class'] = 'toc-backref'
+                atts['href'] = '#' + node['refid']
+            self.body.append(self.starttag({}, 'a', '', **atts))
+            self.context.append('</a></h%s>\n' % (self.section_level))
+
+    def depart_title(self, node):
+        self.body.append(self.context.pop())
+
+    def visit_title_reference(self, node):
+        self.body.append(self.starttag(node, 'cite', ''))
+
+    def depart_title_reference(self, node):
+        self.body.append('</cite>')
+
+    def visit_topic(self, node):
+        self.body.append(self.starttag(node, 'div', CLASS='topic'))
+        self.topic_class = node.get('class')
+
+    def depart_topic(self, node):
+        self.body.append('</div>\n')
+        self.topic_class = ''
+
+    def visit_transition(self, node):
+        self.body.append(self.emptytag(node, 'hr'))
+
+    def depart_transition(self, node):
+        pass
+
+    def visit_version(self, node):
+        self.visit_docinfo_item(node, 'version', meta=None)
+
+    def depart_version(self, node):
+        self.depart_docinfo_item()
+
+    def visit_warning(self, node):
+        self.visit_admonition(node, 'warning')
+
+    def depart_warning(self, node):
+        self.depart_admonition()
+
+    def unimplemented_visit(self, node):
+        raise NotImplementedError('visiting unimplemented node type: %s'
+                                  % node.__class__.__name__)
+
+
+class SimpleListChecker(nodes.GenericNodeVisitor):
+
+    """
+    Raise `nodes.SkipNode` if non-simple list item is encountered.
+
+    Here "simple" means a list item containing nothing other than a single
+    paragraph, a simple list, or a paragraph followed by a simple list.
+    """
+
+    def default_visit(self, node):
+        raise nodes.NodeFound
+
+    def visit_bullet_list(self, node):
+        pass
+
+    def visit_enumerated_list(self, node):
+        pass
+
+    def visit_list_item(self, node):
+        children = []
+        for child in node.get_children():
+            if not isinstance(child, nodes.Invisible):
+                children.append(child)
+        if (children and isinstance(children[0], nodes.paragraph)
+            and (isinstance(children[-1], nodes.bullet_list)
+                 or isinstance(children[-1], nodes.enumerated_list))):
+            children.pop()
+        if len(children) <= 1:
+            return
+        else:
+            raise nodes.NodeFound
+
+    def visit_paragraph(self, node):
+        raise nodes.SkipNode
+
+    def invisible_visit(self, node):
+        """Invisible nodes should be ignored."""
+        pass
+
+    visit_comment = invisible_visit
+    visit_substitution_definition = invisible_visit
+    visit_target = invisible_visit
+    visit_pending = invisible_visit

lib/python/docutils/writers/html4zope.py

+# Author: Andreas Jung
+# Contact: andreas@andreas-jung.com
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:20 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Writer module to integrate reST into Zope.  This writer subclasses the standard
+html4css1 writer and changes the starting level for <H> elements from 1 to 3
+(default behaviour inside Zope.
+"""
+
+__docformat__ = 'reStructuredText'
+
+from docutils import nodes
+from html4css1 import Writer  as CSS1Writer, HTMLTranslator as CSS1HTMLTranslator
+import os
+
+default_level = int(os.environ.get('STX_DEFAULT_LEVEL', 3))
+
+class Writer(CSS1Writer):
+    def __init__(self):
+        CSS1Writer.__init__(self)
+        self.translator_class = HTMLTranslator
+
+class HTMLTranslator(CSS1HTMLTranslator):
+
+    def astext(self):
+        return ''.join(self.body)
+
+    def visit_title(self, node):
+        """Only 6 section levels are supported by HTML."""
+
+        if isinstance(node.parent, nodes.topic):
+            self.body.append(
+                  self.starttag(node, 'p', '', CLASS='topic-title'))
+            if node.parent.hasattr('id'):
+                self.body.append(
+                    self.starttag({}, 'a', '', name=node.parent['id']))
+                self.context.append('</a></p>\n')
+            else:
+                self.context.append('</p>\n')
+        elif self.section_level == 0:
+            # document title
+            self.head.append('<title>%s</title>\n'
+                             % self.encode(node.astext()))
+            self.body.append(self.starttag(node, 'h%d' % default_level, '', CLASS='title'))
+            self.context.append('</h%d>\n' % default_level)
+        else:
+            self.body.append(
+                  self.starttag(node, 'h%s' % (default_level+self.section_level-1), ''))
+            atts = {}
+            if node.parent.hasattr('id'):
+                atts['name'] = node.parent['id']
+            if node.hasattr('refid'):
+                atts['class'] = 'toc-backref'
+                atts['href'] = '#' + node['refid']
+            self.body.append(self.starttag({}, 'a', '', **atts))
+            self.context.append('</a></h%s>\n' % ((default_level+self.section_level-1)))

lib/python/docutils/writers/pep_html.py

+# Author: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:20 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+PEP HTML Writer.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+import sys
+import docutils
+from docutils import nodes, optik, utils
+from docutils.writers import html4css1
+
+
+class Writer(html4css1.Writer):
+
+    settings_spec = html4css1.Writer.settings_spec + (
+        'PEP/HTML-Specific Options',
+        'The HTML --footnote-references option is set to "brackets" by '
+        'default.',
+        (('Specify a PEP stylesheet URL, used verbatim.  Default is '
+          '--stylesheet\'s value.  If given, --pep-stylesheet overrides '
+          '--stylesheet.',
+          ['--pep-stylesheet'],
+          {'metavar': '<URL>'}),
+         ('Specify a PEP stylesheet file, relative to the current working '
+          'directory.  The path is adjusted relative to the output HTML '
+          'file.  Overrides --pep-stylesheet and --stylesheet-path.',
+          ['--pep-stylesheet-path'],
+          {'metavar': '<path>'}),
+         ('Specify a template file.  Default is "pep-html-template".',
+          ['--pep-template'],
+          {'default': 'pep-html-template', 'metavar': '<file>'}),
+         ('Python\'s home URL.  Default is ".." (parent directory).',
+          ['--python-home'],
+          {'default': '..', 'metavar': '<URL>'}),
+         ('Home URL prefix for PEPs.  Default is "." (current directory).',
+          ['--pep-home'],
+          {'default': '.', 'metavar': '<URL>'}),
+         # Workaround for SourceForge's broken Python
+         # (``import random`` causes a segfault).
+         (optik.SUPPRESS_HELP,
+          ['--no-random'], {'action': 'store_true'}),))
+
+    settings_default_overrides = {'footnote_references': 'brackets'}
+
+    relative_path_settings = ('pep_stylesheet_path', 'pep_template')
+
+    def __init__(self):
+        html4css1.Writer.__init__(self)
+        self.translator_class = HTMLTranslator
+
+    def translate(self):
+        html4css1.Writer.translate(self)
+        settings = self.document.settings
+        template = open(settings.pep_template).read()
+        # Substitutions dict for template:
+        subs = {}
+        subs['encoding'] = settings.output_encoding
+        subs['version'] = docutils.__version__
+        subs['stylesheet'] = ''.join(self.stylesheet)
+        pyhome = settings.python_home
+        subs['pyhome'] = pyhome
+        subs['pephome'] = settings.pep_home
+        if pyhome == '..':
+            subs['pepindex'] = '.'
+        else:
+            subs['pepindex'] = pyhome + '/peps/'
+        index = self.document.first_child_matching_class(nodes.field_list)
+        header = self.document[index]
+        pepnum = header[0][1].astext()
+        subs['pep'] = pepnum
+        if settings.no_random:
+            subs['banner'] = 0
+        else:
+            import random
+            subs['banner'] = random.randrange(64)
+        try:
+            subs['pepnum'] = '%04i' % int(pepnum)
+        except:
+            subs['pepnum'] = pepnum
+        subs['title'] = header[1][1].astext()
+        subs['body'] = ''.join(
+            self.body_pre_docinfo + self.docinfo + self.body)
+        subs['body_suffix'] = ''.join(self.body_suffix)
+        self.output = template % subs
+
+
+class HTMLTranslator(html4css1.HTMLTranslator):
+
+    def get_stylesheet_reference(self, relative_to=None):
+        settings = self.settings
+        if relative_to == None:
+            relative_to = settings._destination
+        if settings.pep_stylesheet_path:
+            return utils.relative_path(relative_to,
+                                       settings.pep_stylesheet_path)
+        elif settings.pep_stylesheet:
+            return settings.pep_stylesheet
+        elif settings._stylesheet_path:
+            return utils.relative_path(relative_to, settings.stylesheet_path)
+        else:
+            return settings.stylesheet
+
+    def depart_field_list(self, node):
+        html4css1.HTMLTranslator.depart_field_list(self, node)
+        if node.get('class') == 'rfc2822':
+             self.body.append('<hr />\n')

lib/python/docutils/writers/pseudoxml.py

+# Authors: David Goodger
+# Contact: goodger@users.sourceforge.net
+# Revision: $Revision: 1.2 $
+# Date: $Date: 2003/02/01 09:26:20 $
+# Copyright: This module has been placed in the public domain.
+
+"""
+Simple internal document tree Writer, writes indented pseudo-XML.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+from docutils import writers
+
+
+class Writer(writers.Writer):
+
+    supported = ('pprint', 'pformat', 'pseudoxml')
+    """Formats this writer supports."""
+
+    output = None
+    """Final translated form of `document`."""
+
+    def translate(self):
+        self.output = self.document.pformat()
+
+    def supports(self, format):
+        """This writer supports all format-specific elements."""
+        return 1

lib/python/reStructuredText/__init__.py

+##############################################################################
+#
+# Copyright (c) 2001 Zope Corporation and Contributors. All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE
+#
+##############################################################################
+
+""" Wrapper to integrate reStructuredText into Zope """
+
+__all__ = ["HTML" ]
+
+import docutils.core 
+from docutils.io import StringOutput, StringInput 
+import sys
+
+class Warnings:
+    def __init__(self):
+        self.messages = []
+
+    def write(self, message):
+        self.messages.append(message)
+
+
+def HTML(src, writer='html4zope', report_level=1, stylesheet='default.css',
+         input_encoding=None, output_encoding=None):
+    """ render HTML from a reStructuredText string 
+
+        - 'src'  -- string containing a valid reST document
+
+        - 'writer' -- docutils writer 
+
+        - 'report_level' - verbosity of reST parser
+
+        - 'stylesheet' - Stylesheet to be used
+    """
+
+    pub = docutils.core.Publisher()
+    pub.set_reader('standalone', None, 'restructuredtext')
+    pub.set_writer(writer)
+
+    if input_encoding is None:
+        input_encoding = sys.getdefaultencoding()
+
+    if output_encoding is None:
+        output_encoding = sys.getdefaultencoding()
+
+    # go with the defaults
+    pub.get_settings()
+
+    pub.settings.stylesheet = stylesheet
+
+    # this is needed, but doesn't seem to do anything
+    pub.settings._destination = ''
+
+    # set the reporting level to something sane
+    pub.settings.report_level = report_level
+
+    # don't break if we get errors
+    pub.settings.halt_level = 6
+
+    # remember warnings
+    pub.settings.warning_stream = Warnings()
+
+    # input
+    pub.source = StringInput(source=src, encoding=input_encoding)
+
+    # output - not that it's needed
+    pub.destination = StringOutput(encoding=output_encoding)
+
+    # parse!
+    document = pub.reader.read(pub.source, pub.parser, pub.settings)
+    warnings = ''.join(pub.settings.warning_stream.messages)
+
+    # do the format
+    print pub.writer.write(document, pub.destination)
+    return pub.writer.write(document, pub.destination)
+