`_: Unicode
+ file breaks InputStream.
+
+* Source code is now mostly PEP 8 compliant.
+
+* Test harness has been improved and now depends on ``nose``.
0.95
diff --git a/README.rst b/README.rst
index f38b9426..af4c1fe8 100644
--- a/README.rst
+++ b/README.rst
@@ -1,63 +1,98 @@
html5lib
========
+.. image:: https://travis-ci.org/html5lib/html5lib-python.png?branch=master
+ :target: https://travis-ci.org/html5lib/html5lib-python
+
html5lib is a pure-python library for parsing HTML. It is designed to
conform to the WHATWG HTML specification, as is implemented by all major
web browsers.
-Requirements
-------------
+Usage
+-----
-Python 2.6 and above as well as Python 3.0 and above are
-supported. Implementations known to work are CPython (as the reference
-implementation) and PyPy. Jython is known *not* to work due to various
-bugs in its implementation of the language. Others such as IronPython
-may or may not work; if you wish to try, you are strongly encouraged
-to run the testsuite and report back!
+Simple usage follows this pattern:
-The only required library dependency is ``six``, this can be found
-packaged in PyPI.
+.. code-block:: python
-Optionally:
+ import html5lib
+ with open("mydocument.html", "rb") as f:
+ document = html5lib.parse(f)
-- ``datrie`` can be used to improve parsing performance (though in
- almost all cases the improvement is marginal);
+or:
-- ``lxml`` is supported as a tree format (for both building and
- walking) under CPython (but *not* PyPy where it is known to cause
- segfaults);
+.. code-block:: python
-- ``genshi`` has a treewalker (but not builder); and
+ import html5lib
+ document = html5lib.parse("Hello World!")
-- ``charade`` can be used as a fallback when character encoding cannot
- be determined; ``chardet``, from which it was forked, can also be used
- on Python 2.
+By default, the ``document`` will be an ``xml.etree`` element instance.
+Whenever possible, html5lib chooses the accelerated ``ElementTree``
+implementation (i.e. ``xml.etree.cElementTree`` on Python 2.x).
+
+Two other tree types are supported: ``xml.dom.minidom`` and
+``lxml.etree``. To use an alternative format, specify the name of
+a treebuilder:
+
+.. code-block:: python
+
+ import html5lib
+ with open("mydocument.html", "rb") as f:
+ lxml_etree_document = html5lib.parse(f, treebuilder="lxml")
+
+To have more control over the parser, create a parser object explicitly.
+For instance, to make the parser raise exceptions on parse errors, use:
+
+.. code-block:: python
+
+ import html5lib
+ with open("mydocument.html", "rb") as f:
+ parser = html5lib.HTMLParser(strict=True)
+ document = parser.parse(f)
+
+When you're instantiating parser objects explicitly, pass a treebuilder
+class as the ``tree`` keyword argument to use an alternative document
+format:
+
+.. code-block:: python
+
+ import html5lib
+ parser = html5lib.HTMLParser(tree=html5lib.getTreeBuilder("dom"))
+ minidom_document = parser.parse("
Hello World!")
+
+More documentation is available at http://html5lib.readthedocs.org/.
Installation
------------
-html5lib is packaged with distutils. To install it use::
+html5lib works on CPython 2.6+, CPython 3.2+ and PyPy. To install it,
+use:
- $ python setup.py install
+.. code-block:: bash
+ $ pip install html5lib
-Usage
------
-Simple usage follows this pattern::
+Optional Dependencies
+---------------------
- import html5lib
- with open("mydocument.html", "r") as fp:
- document = html5lib.parse(f)
+The following third-party libraries may be used for additional
+functionality:
-or::
+- ``datrie`` can be used to improve parsing performance (though in
+ almost all cases the improvement is marginal);
- import html5lib
- document = html5lib.parse("
Hello World!")
+- ``lxml`` is supported as a tree format (for both building and
+ walking) under CPython (but *not* PyPy where it is known to cause
+ segfaults);
-More documentation is available in the docstrings.
+- ``genshi`` has a treewalker (but not builder); and
+
+- ``charade`` can be used as a fallback when character encoding cannot
+ be determined; ``chardet``, from which it was forked, can also be used
+ on Python 2.
Bugs
@@ -70,28 +105,21 @@ Please report any bugs on the `issue tracker
Tests
-----
-These are contained in the html5lib-tests repository and included as a
-submodule, thus for git checkouts they must be initialized (for
-release tarballs this is unneeded)::
+Unit tests require the ``nose`` library and can be run using the
+``nosetests`` command in the root directory. All should pass.
+
+Test data are contained in a separate `html5lib-tests
+`_ repository and included
+as a submodule, thus for git checkouts they must be initialized::
$ git submodule init
$ git submodule update
-And then they can be run, with ``nose`` installed, using the
-``nosetests`` command in the root directory. All should pass.
+This is unneeded for release tarballs.
If you have all compatible Python implementations available on your
-system, you can run tests on all of them by using tox::
-
- $ pip install tox
- $ tox
- ...
- _______________________ summary ______________________
- py26: commands succeeded
- py27: commands succeeded
- py32: commands succeeded
- py33: commands succeeded
- congratulations :)
+system, you can run tests on all of them using the ``tox`` utility,
+which can be found on PyPI.
Contributing
@@ -121,5 +149,5 @@ Questions?
There's a mailing list available for support on Google Groups,
`html5lib-discuss `_,
-though you may have more success (and get a far quicker response)
-asking on IRC in #whatwg on irc.freenode.net.
+though you may get a quicker response asking on IRC in #whatwg on
+irc.freenode.net.