Added to README a section on unicode string handling.

1 files changed, 28 insertions, 0 deletions

diff --git a/README.rst b/README.rst
index 39f3840..ae3ef8f 100644
--- a/README.rst
+++ b/README.rst
@@ -73,6 +73,33 @@ Pull it together::
     u'Hello, Pizza!'
 
 
+Unicode
+=======
+
+This section describes Pystache's handling of unicode, strings, and encodings.
+Pystache's template rendering methods output only unicode.  Moreover,
+internally Pystache uses only unicode strings.  For input, Pystache accepts
+both ``unicode`` and ``str`` strings.
+
+The Renderer class supports a number of attributes that control how it
+converts ``str`` strings to unicode on input.  These attributes 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 strings of type str
+to unicode (e.g. context values of type ``str``).  The decode_errors
+attribute is what the renderer passes as the ``errors`` argument to
+Python's built-in `unicode()`_ function.  The valid values are 'strict',
+'ignore', or 'replace'.
+
+Each of these attributes can be set via the Renderer class's constructor
+using a keyword argument of the same name.  In addition, the file_encoding
+attribute can be controlled on a per-view basis by subclassing the
+`TemplateSpec` class.  The attributes default to values set in Pystache's
+``defaults`` module.
+
+
 Test It
 =======
 
@@ -136,4 +163,5 @@ Author
 .. _PyPI: http://pypi.python.org/pypi/pystache
 .. _Pystache: https://github.com/defunkt/pystache
 .. _semantically versioned: http://semver.org
+.. _unicode(): http://docs.python.org/library/functions.html#unicode
 .. _version 1.0.3: https://github.com/mustache/spec/tree/48c933b0bb780875acbfd15816297e263c53d6f7