new file mode 100644
--- /dev/null
+++ b/doc/xpath.txt
@@ -0,0 +1,92 @@
+.. -*- mode: rst; encoding: utf-8 -*-
+
+=====================
+Using XPath in Markup
+=====================
+
+Markup provides basic XPath_ support for matching and querying event streams.
+
+.. _xpath: http://www.w3.org/TR/xpath
+
+
+.. contents:: Contents
+   :depth: 2
+.. sectnum::
+
+
+-----------
+Limitations
+-----------
+
+Due to the streaming nature of the processing model, Markup uses only a subset
+of the `XPath 1.0`_ language.
+
+.. _`XPath 1.0`: http://www.w3.org/TR/xpath
+
+In particular, only the following axes are supported:
+
+* ``attribute``
+* ``child``
+* ``descendant``
+* ``descendant-or-self``
+* ``self``
+
+This means you can't use the ``parent``, ancestor, or sibling axes in Markup
+(the ``namespace`` axis isn't supported either, but what you'd ever need that
+for I don't know). Basically, any path expression that would require buffering
+of the stream is not supported.
+
+Predicates are of course supported, but Path expressions *inside* predicates
+are restricted to attribute lookups (again due to the lack of buffering).
+
+Most of the XPath functions and operators are supported, however they
+(currently) only work inside predicates. The following functions are **not**
+supported:
+
+* ``count()``
+* ``id()``
+* ``lang()``
+* ``last()``
+* ``position()``
+* ``string()``
+* ``sum()``
+
+The mathematical operators (``+``, ``-``, ``*``, ``div``, and ``mod``) are not
+yet supported, whereas the various comparison and logical operators should work
+as expected.
+
+You can also use XPath variable references (``$var``) inside predicates.
+
+
+----------------
+Querying Streams
+----------------
+
+::
+
+  from markup.input import XML
+
+  doc = XML('''<doc>
+   <items count="2">
+        <item status="new">
+          <summary>Foo</summary>
+        </item>
+        <item status="closed">
+          <summary>Bar</summary>
+        </item>
+    </items>
+  </doc>''')
+  print doc.select('items/item[@status="closed"]/summary/text()')
+
+This would result in the following output::
+
+  Bar
+
+
+---------------------
+Matching in Templates
+---------------------
+
+See the directive ``py:match`` in the `XML Template Language Specification`_.
+
+.. _`XML Template Language Specification`: xml-templates.html