Regenerated .rst README and HISTORY from .md versions using pandoc.

2 files changed, 245 insertions, 208 deletions

diff --git a/HISTORY.rst b/HISTORY.rst
index 6ec24dd..e03c60e 100644
--- a/HISTORY.rst
+++ b/HISTORY.rst
@@ -4,126 +4,143 @@ History
 0.5.3 (TBD)
 -----------
 
-* Added option of raising errors on missing tags/partials:
-  ``Renderer(missing_tags='strict')`` (issue #110).
-* Added a ``parse()`` function that yields a printable, pre-compiled parse tree.
-* Added support for rendering pre-compiled templates.
-* Bugfix: exceptions raised from a property are no longer swallowed when
-  getting a key from a context stack (issue #110).
-* Bugfix: lambda section values can now return non-ascii, non-unicode strings (issue #118).
-* More robust handling of byte strings in Python 3.
+-  Added option of raising errors on missing tags/partials:
+   ``Renderer(missing_tags='strict')`` (issue #110).
+-  Added a ``parse()`` function that yields a printable, pre-compiled
+   parse tree.
+-  Added support for rendering pre-compiled templates.
+-  Bugfix: exceptions raised from a property are no longer swallowed
+   when getting a key from a context stack (issue #110).
+-  Bugfix: lambda section values can now return non-ascii, non-unicode
+   strings (issue #118).
+-  More robust handling of byte strings in Python 3.
 
 0.5.2 (2012-05-03)
 ------------------
 
-* Added support for dot notation and version 1.1.2 of the spec (issue #99). [rbp]
-* Missing partials now render as empty string per latest version of spec (issue #115).
-* Bugfix: falsey values now coerced to strings using str().
-* Bugfix: lambda return values for sections no longer pushed onto context stack (issue #113).
-* Bugfix: lists of lambdas for sections were not rendered (issue #114).
+-  Added support for dot notation and version 1.1.2 of the spec (issue
+   #99). [rbp]
+-  Missing partials now render as empty string per latest version of
+   spec (issue #115).
+-  Bugfix: falsey values now coerced to strings using str().
+-  Bugfix: lambda return values for sections no longer pushed onto
+   context stack (issue #113).
+-  Bugfix: lists of lambdas for sections were not rendered (issue #114).
 
 0.5.1 (2012-04-24)
 ------------------
 
-* Added support for Python 3.1 and 3.2.
-* Added tox support to test multiple Python versions.
-* Added test script entry point: pystache-test.
-* Added __version__ package attribute.
-* Test harness now supports both YAML and JSON forms of Mustache spec.
-* Test harness no longer requires nose.
+-  Added support for Python 3.1 and 3.2.
+-  Added tox support to test multiple Python versions.
+-  Added test script entry point: pystache-test.
+-  Added \_\_version\_\_ package attribute.
+-  Test harness now supports both YAML and JSON forms of Mustache spec.
+-  Test harness no longer requires nose.
 
 0.5.0 (2012-04-03)
 ------------------
 
 This version represents a major rewrite and refactoring of the code base
-that also adds features and fixes many bugs.  All functionality and nearly
-all unit tests have been preserved.  However, some backwards incompatible
-changes to the API have been made.
+that also adds features and fixes many bugs. All functionality and
+nearly all unit tests have been preserved. However, some backwards
+incompatible changes to the API have been made.
 
 Below is a selection of some of the changes (not exhaustive).
 
 Highlights:
 
-* Pystache now passes all tests in version 1.0.3 of the `Mustache spec`_. [pvande]
-* Removed View class: it is no longer necessary to subclass from View or
-  from any other class to create a view.
-* Replaced Template with Renderer class: template rendering behavior can be
-  modified via the Renderer constructor or by setting attributes on a Renderer instance.
-* Added TemplateSpec class: template rendering can be specified on a per-view
-  basis by subclassing from TemplateSpec.
-* Introduced separation of concerns and removed circular dependencies (e.g.
-  between Template and View classes, cf. `issue #13`_).
-* Unicode now used consistently throughout the rendering process.
-* Expanded test coverage: nosetests now runs doctests and ~105 test cases
-  from the Mustache spec (increasing the number of tests from 56 to ~315).
-* Added a rudimentary benchmarking script to gauge performance while refactoring.
-* Extensive documentation added (e.g. docstrings).
+-  Pystache now passes all tests in version 1.0.3 of the `Mustache
+   spec <https://github.com/mustache/spec>`_. [pvande]
+-  Removed View class: it is no longer necessary to subclass from View
+   or from any other class to create a view.
+-  Replaced Template with Renderer class: template rendering behavior
+   can be modified via the Renderer constructor or by setting attributes
+   on a Renderer instance.
+-  Added TemplateSpec class: template rendering can be specified on a
+   per-view basis by subclassing from TemplateSpec.
+-  Introduced separation of concerns and removed circular dependencies
+   (e.g. between Template and View classes, cf. `issue
+   #13 <https://github.com/defunkt/pystache/issues/13>`_).
+-  Unicode now used consistently throughout the rendering process.
+-  Expanded test coverage: nosetests now runs doctests and ~105 test
+   cases from the Mustache spec (increasing the number of tests from 56
+   to ~315).
+-  Added a rudimentary benchmarking script to gauge performance while
+   refactoring.
+-  Extensive documentation added (e.g. docstrings).
 
 Other changes:
 
-* Added a command-line interface. [vrde]
-* The main rendering class now accepts a custom partial loader (e.g. a dictionary)
-  and a custom escape function.
-* Non-ascii characters in str strings are now supported while rendering.
-* Added string encoding, file encoding, and errors options for decoding to unicode.
-* Removed the output encoding option.
-* Removed the use of markupsafe.
+-  Added a command-line interface. [vrde]
+-  The main rendering class now accepts a custom partial loader (e.g. a
+   dictionary) and a custom escape function.
+-  Non-ascii characters in str strings are now supported while
+   rendering.
+-  Added string encoding, file encoding, and errors options for decoding
+   to unicode.
+-  Removed the output encoding option.
+-  Removed the use of markupsafe.
 
 Bug fixes:
 
-* Context values no longer processed as template strings. [jakearchibald]
-* Whitespace surrounding sections is no longer altered, per the spec. [heliodor]
-* Zeroes now render correctly when using PyPy. [alex]
-* Multline comments now permitted. [fczuardi]
-* Extensionless template files are now supported.
-* Passing ``**kwargs`` to ``Template()`` no longer modifies the context.
-* Passing ``**kwargs`` to ``Template()`` with no context no longer raises an exception.
+-  Context values no longer processed as template strings.
+   [jakearchibald]
+-  Whitespace surrounding sections is no longer altered, per the spec.
+   [heliodor]
+-  Zeroes now render correctly when using PyPy. [alex]
+-  Multline comments now permitted. [fczuardi]
+-  Extensionless template files are now supported.
+-  Passing ``**kwargs`` to ``Template()`` no longer modifies the
+   context.
+-  Passing ``**kwargs`` to ``Template()`` with no context no longer
+   raises an exception.
 
 0.4.1 (2012-03-25)
 ------------------
-* Added support for Python 2.4. [wangtz, jvantuyl]
+
+-  Added support for Python 2.4. [wangtz, jvantuyl]
 
 0.4.0 (2011-01-12)
 ------------------
-* Add support for nested contexts (within template and view)
-* Add support for inverted lists
-* Decoupled template loading
+
+-  Add support for nested contexts (within template and view)
+-  Add support for inverted lists
+-  Decoupled template loading
 
 0.3.1 (2010-05-07)
 ------------------
 
-* Fix package
+-  Fix package
 
 0.3.0 (2010-05-03)
 ------------------
 
-* View.template_path can now hold a list of path
-* Add {{& blah}} as an alias for {{{ blah }}}
-* Higher Order Sections
-* Inverted sections
+-  View.template\_path can now hold a list of path
+-  Add {{& blah}} as an alias for {{{ blah }}}
+-  Higher Order Sections
+-  Inverted sections
 
 0.2.0 (2010-02-15)
 ------------------
 
-* Bugfix: Methods returning False or None are not rendered
-* Bugfix: Don't render an empty string when a tag's value is 0. [enaeseth]
-* Add support for using non-callables as View attributes. [joshthecoder]
-* Allow using View instances as attributes. [joshthecoder]
-* Support for Unicode and non-ASCII-encoded bytestring output. [enaeseth]
-* Template file encoding awareness. [enaeseth]
+-  Bugfix: Methods returning False or None are not rendered
+-  Bugfix: Don't render an empty string when a tag's value is 0.
+   [enaeseth]
+-  Add support for using non-callables as View attributes.
+   [joshthecoder]
+-  Allow using View instances as attributes. [joshthecoder]
+-  Support for Unicode and non-ASCII-encoded bytestring output.
+   [enaeseth]
+-  Template file encoding awareness. [enaeseth]
 
 0.1.1 (2009-11-13)
 ------------------
 
-* Ensure we're dealing with strings, always
-* Tests can be run by executing the test file directly
+-  Ensure we're dealing with strings, always
+-  Tests can be run by executing the test file directly
 
 0.1.0 (2009-11-12)
 ------------------
 
-* First release
-
+-  First release
 
-.. _2to3: http://docs.python.org/library/2to3.html
-.. _issue #13: https://github.com/defunkt/pystache/issues/13
-.. _Mustache spec: https://github.com/mustache/spec
diff --git a/README.rst b/README.rst
index c8d8446..e657572 100644
--- a/README.rst
+++ b/README.rst
@@ -1,61 +1,72 @@
-========
 Pystache
 ========
 
-.. image:: https://s3.amazonaws.com/webdev_bucket/pystache.png
-
-Pystache_ is a Python implementation of Mustache_.
-Mustache is a framework-agnostic, logic-free templating system inspired
-by ctemplate_ and et_.  Like ctemplate, Mustache "emphasizes
-separating logic from presentation: it is impossible to embed application
-logic in this template language."
+.. figure:: https://s3.amazonaws.com/webdev_bucket/pystache.png
+   :align: center
+   :alt: image
 
-The `mustache(5)`_ man page provides a good introduction to Mustache's
-syntax.  For a more complete (and more current) description of Mustache's
-behavior, see the official `Mustache spec`_.
+   image
+`Pystache <https://github.com/defunkt/pystache>`_ is a Python
+implementation of `Mustache <http://mustache.github.com/>`_. Mustache is
+a framework-agnostic, logic-free templating system inspired by
+`ctemplate <http://code.google.com/p/google-ctemplate/>`_ and
+`et <http://www.ivan.fomichev.name/2008/05/erlang-template-engine-prototype.html>`_.
+Like ctemplate, Mustache "emphasizes separating logic from presentation:
+it is impossible to embed application logic in this template language."
 
-Pystache is `semantically versioned`_ and can be found on PyPI_.  This
-version of Pystache passes all tests in `version 1.1.2`_ of the spec.
+The `mustache(5) <http://mustache.github.com/mustache.5.html>`_ man page
+provides a good introduction to Mustache's syntax. For a more complete
+(and more current) description of Mustache's behavior, see the official
+`Mustache spec <https://github.com/mustache/spec>`_.
 
-Logo: `David Phillips`_
+Pystache is `semantically versioned <http://semver.org>`_ and can be
+found on `PyPI <http://pypi.python.org/pypi/pystache>`_. This version of
+Pystache passes all tests in `version
+1.1.2 <https://github.com/mustache/spec/tree/v1.1.2>`_ of the spec.
 
+Logo: `David Phillips <http://davidphillips.us/>`_
 
 Requirements
-============
+------------
 
 Pystache is tested with--
 
-* Python 2.4 (requires simplejson `version 2.0.9`_ or earlier)
-* Python 2.5 (requires simplejson_)
-* Python 2.6
-* Python 2.7
-* Python 3.1
-* Python 3.2
-
-JSON support is needed only for the command-line interface and to run the
-spec tests.  We require simplejson for earlier versions of Python since
-Python's json_ module was added in Python 2.6.
+-  Python 2.4 (requires simplejson `version
+   2.0.9 <http://pypi.python.org/pypi/simplejson/2.0.9>`_ or earlier)
+-  Python 2.5 (requires
+   `simplejson <http://pypi.python.org/pypi/simplejson/>`_)
+-  Python 2.6
+-  Python 2.7
+-  Python 3.1
+-  Python 3.2
+
+JSON support is needed only for the command-line interface and to run
+the spec tests. We require simplejson for earlier versions of Python
+since Python's `json <http://docs.python.org/library/json.html>`_ module
+was added in Python 2.6.
+
+For Python 2.4 we require an earlier version of simplejson since
+simplejson stopped officially supporting Python 2.4 in simplejson
+version 2.1.0. Earlier versions of simplejson can be installed manually,
+as follows:
 
-For Python 2.4 we require an earlier version of simplejson since simplejson
-stopped officially supporting Python 2.4 in simplejson version 2.1.0.
-Earlier versions of simplejson can be installed manually, as follows: ::
+::
 
     pip install 'simplejson<2.1.0'
 
-
 Install It
-==========
+----------
 
 ::
 
     pip install pystache
     pystache-test
 
-To install and test from source (e.g. from GitHub), see the Develop section.
-
+To install and test from source (e.g. from GitHub), see the Develop
+section.
 
 Use It
-======
+------
 
 ::
 
@@ -65,152 +76,186 @@ Use It
 
 You can also create dedicated view classes to hold your view logic.
 
-Here's your view class (in .../examples/readme.py)::
+Here's your view class (in .../examples/readme.py):
+
+::
 
     class SayHello(object):
         def to(self):
             return "Pizza"
 
-Instantiating like so::
+Instantiating like so:
+
+::
 
     >>> from pystache.tests.examples.readme import SayHello
     >>> hello = SayHello()
 
-Then your template, say_hello.mustache (by default in the same directory
-as your class definition)::
+Then your template, say\_hello.mustache (by default in the same
+directory as your class definition):
+
+::
 
     Hello, {{to}}!
 
-Pull it together::
+Pull it together:
+
+::
 
     >>> renderer = pystache.Renderer()
     >>> print renderer.render(hello)
     Hello, Pizza!
 
-For greater control over rendering (e.g. to specify a custom template directory),
-use the ``Renderer`` class like above.  One can pass attributes to the
-Renderer class constructor or set them on a Renderer instance.
-To customize template loading on a per-view basis, subclass ``TemplateSpec``.
-See the docstrings of the Renderer_ class and TemplateSpec_ class for
-more information.
+For greater control over rendering (e.g. to specify a custom template
+directory), use the ``Renderer`` class like above. One can pass
+attributes to the Renderer class constructor or set them on a Renderer
+instance. To customize template loading on a per-view basis, subclass
+``TemplateSpec``. See the docstrings of the
+`Renderer <https://github.com/defunkt/pystache/blob/master/pystache/renderer.py>`_
+class and
+`TemplateSpec <https://github.com/defunkt/pystache/blob/master/pystache/template_spec.py>`_
+class for more information.
 
-You can also pre-parse a template: ::
+You can also pre-parse a template:
+
+::
 
     >>> parsed = pystache.parse(u"Hey {{#who}}{{.}}!{{/who}}")
     >>> print parsed
     [u'Hey ', _SectionNode(key=u'who', index_begin=12, index_end=18, parsed=[_EscapeNode(key=u'.'), u'!'])]
 
-And then::
+And then:
+
+::
 
     >>> print renderer.render(parsed, {'who': 'Pops'})
     Hey Pops!
     >>> print renderer.render(parsed, {'who': 'you'})
     Hey you!
 
-
 Python 3
-========
+--------
 
-Pystache has supported Python 3 since version 0.5.1.  Pystache behaves
+Pystache has supported Python 3 since version 0.5.1. Pystache behaves
 slightly differently between Python 2 and 3, as follows:
 
-* In Python 2, the default html-escape function ``cgi.escape()`` does not
-  escape single quotes; whereas in Python 3, the default escape function
-  ``html.escape()`` does escape single quotes.
-* In both Python 2 and 3, the string and file encodings default to
-  ``sys.getdefaultencoding()``.  However, this function can return different
-  values under Python 2 and 3, even when run from the same system.  Check
-  your own system for the behavior on your system, or do not rely on the
-  defaults by passing in the encodings explicitly (e.g. to the ``Renderer`` class).
-
+-  In Python 2, the default html-escape function ``cgi.escape()`` does
+   not escape single quotes; whereas in Python 3, the default escape
+   function ``html.escape()`` does escape single quotes.
+-  In both Python 2 and 3, the string and file encodings default to
+   ``sys.getdefaultencoding()``. However, this function can return
+   different values under Python 2 and 3, even when run from the same
+   system. Check your own system for the behavior on your system, or do
+   not rely on the defaults by passing in the encodings explicitly (e.g.
+   to the ``Renderer`` class).
 
 Unicode
-=======
-
-This section describes how Pystache handles unicode, strings, and encodings.
-
-Internally, Pystache uses `only unicode strings`_ (``str`` in Python 3 and
-``unicode`` in Python 2).  For input, Pystache accepts both unicode strings
-and byte strings (``bytes`` in Python 3 and ``str`` in Python 2).  For output,
-Pystache's template rendering methods return only unicode.
-
-Pystache's ``Renderer`` class supports a number of attributes to control how
-Pystache converts byte strings to unicode on input.  These include the
-``file_encoding``, ``string_encoding``, and ``decode_errors`` attributes.
-
-The ``file_encoding`` attribute is the encoding the renderer uses to convert
-to unicode any files read from the file system.  Similarly, ``string_encoding``
-is the encoding the renderer uses to convert any other byte strings encountered
-during the rendering process into unicode (e.g. context values that are
-encoded byte strings).
-
-The ``decode_errors`` attribute is what the renderer passes as the ``errors``
-argument to Python's built-in unicode-decoding function (``str()`` in Python 3
-and ``unicode()`` in Python 2).  The valid values for this argument are
-``strict``, ``ignore``, and ``replace``.
-
-Each of these attributes can be set via the ``Renderer`` class's constructor
-using a keyword argument of the same name.  See the Renderer class's
-docstrings for further details.  In addition, the ``file_encoding``
-attribute can be controlled on a per-view basis by subclassing the
-``TemplateSpec`` class.  When not specified explicitly, these attributes
-default to values set in Pystache's ``defaults`` module.
-
+-------
+
+This section describes how Pystache handles unicode, strings, and
+encodings.
+
+Internally, Pystache uses `only unicode
+strings <http://docs.python.org/howto/unicode.html#tips-for-writing-unicode-aware-programs>`_
+(``str`` in Python 3 and ``unicode`` in Python 2). For input, Pystache
+accepts both unicode strings and byte strings (``bytes`` in Python 3 and
+``str`` in Python 2). For output, Pystache's template rendering methods
+return only unicode.
+
+Pystache's ``Renderer`` class supports a number of attributes to control
+how Pystache converts byte strings to unicode on input. These include
+the ``file_encoding``, ``string_encoding``, and ``decode_errors``
+attributes.
+
+The ``file_encoding`` attribute is the encoding the renderer uses to
+convert to unicode any files read from the file system. Similarly,
+``string_encoding`` is the encoding the renderer uses to convert any
+other byte strings encountered during the rendering process into unicode
+(e.g. context values that are encoded byte strings).
+
+The ``decode_errors`` attribute is what the renderer passes as the
+``errors`` argument to Python's built-in unicode-decoding function
+(``str()`` in Python 3 and ``unicode()`` in Python 2). The valid values
+for this argument are ``strict``, ``ignore``, and ``replace``.
+
+Each of these attributes can be set via the ``Renderer`` class's
+constructor using a keyword argument of the same name. See the Renderer
+class's docstrings for further details. In addition, the
+``file_encoding`` attribute can be controlled on a per-view basis by
+subclassing the ``TemplateSpec`` class. When not specified explicitly,
+these attributes default to values set in Pystache's ``defaults``
+module.
 
 Develop
-=======
+-------
 
-To test from a source distribution (without installing)-- ::
+To test from a source distribution (without installing)--
+
+::
 
     python test_pystache.py
 
-To test Pystache with multiple versions of Python (with a single command!),
-you can use tox_: ::
+To test Pystache with multiple versions of Python (with a single
+command!), you can use `tox <http://pypi.python.org/pypi/tox>`_:
+
+::
 
     pip install tox
     tox
 
-If you do not have all Python versions listed in ``tox.ini``-- ::
+If you do not have all Python versions listed in ``tox.ini``--
+
+::
 
     tox -e py26,py32  # for example
 
 The source distribution tests also include doctests and tests from the
-Mustache spec.  To include tests from the Mustache spec in your test runs: ::
+Mustache spec. To include tests from the Mustache spec in your test
+runs:
+
+::
 
     git submodule init
     git submodule update
 
-The test harness parses the spec's (more human-readable) yaml files if PyYAML_
-is present.  Otherwise, it parses the json files.  To install PyYAML-- ::
+The test harness parses the spec's (more human-readable) yaml files if
+`PyYAML <http://pypi.python.org/pypi/PyYAML>`_ is present. Otherwise, it
+parses the json files. To install PyYAML--
+
+::
 
     pip install pyyaml
 
-To run a subset of the tests, you can use nose_: ::
+To run a subset of the tests, you can use
+`nose <http://somethingaboutorange.com/mrl/projects/nose/0.11.1/testing.html>`_:
+
+::
 
     pip install nose
     nosetests --tests pystache/tests/test_context.py:GetValueTests.test_dictionary__key_present
 
-**Running Pystache from source with Python 3.**  Pystache is written in
-Python 2 and must be converted with 2to3_ prior to running under Python 3.
-The installation process (and tox) do this conversion automatically.
+**Running Pystache from source with Python 3.** Pystache is written in
+Python 2 and must be converted with
+`2to3 <http://docs.python.org/library/2to3.html>`_ prior to running
+under Python 3. The installation process (and tox) do this conversion
+automatically.
 
 To ``import pystache`` from a source distribution while using Python 3,
 be sure that you are importing from a directory containing a converted
-version (e.g. from your site-packages directory after manually installing)
-and not from the original source directory.  Otherwise, you will get a
-syntax error.  You can help ensure this by not running the Python IDE
-from the project directory when importing Pystache.
-
+version (e.g. from your site-packages directory after manually
+installing) and not from the original source directory. Otherwise, you
+will get a syntax error. You can help ensure this by not running the
+Python IDE from the project directory when importing Pystache.
 
 Mailing List
-============
-
-There is a `mailing list`_.  Note that there is a bit of a delay between
-posting a message and seeing it appear in the mailing list archive.
+------------
 
+There is a `mailing list <http://librelist.com/browser/pystache/>`_.
+Note that there is a bit of a delay between posting a message and seeing
+it appear in the mailing list archive.
 
 Authors
-=======
+-------
 
 ::
 
@@ -219,28 +264,3 @@ Authors
     Author: Chris Wanstrath
     Maintainer: Chris Jerdonek
 
-
-.. _2to3: http://docs.python.org/library/2to3.html
-.. _built-in unicode function: http://docs.python.org/library/functions.html#unicode
-.. _ctemplate: http://code.google.com/p/google-ctemplate/
-.. _David Phillips: http://davidphillips.us/
-.. _Distribute: http://pypi.python.org/pypi/distribute
-.. _et: http://www.ivan.fomichev.name/2008/05/erlang-template-engine-prototype.html
-.. _json: http://docs.python.org/library/json.html
-.. _mailing list: http://librelist.com/browser/pystache/
-.. _Mustache: http://mustache.github.com/
-.. _Mustache spec: https://github.com/mustache/spec
-.. _mustache(5): http://mustache.github.com/mustache.5.html
-.. _nose: http://somethingaboutorange.com/mrl/projects/nose/0.11.1/testing.html
-.. _only unicode strings: http://docs.python.org/howto/unicode.html#tips-for-writing-unicode-aware-programs
-.. _PyPI: http://pypi.python.org/pypi/pystache
-.. _Pystache: https://github.com/defunkt/pystache
-.. _PyYAML: http://pypi.python.org/pypi/PyYAML
-.. _Renderer: https://github.com/defunkt/pystache/blob/master/pystache/renderer.py
-.. _semantically versioned: http://semver.org
-.. _simplejson: http://pypi.python.org/pypi/simplejson/
-.. _TemplateSpec: https://github.com/defunkt/pystache/blob/master/pystache/template_spec.py
-.. _test: http://packages.python.org/distribute/setuptools.html#test
-.. _tox: http://pypi.python.org/pypi/tox
-.. _version 1.1.2: https://github.com/mustache/spec/tree/v1.1.2
-.. _version 2.0.9: http://pypi.python.org/pypi/simplejson/2.0.9