diff --git a/HISTORY.txt b/HISTORY.txt
index 1245593..5afb2de 100644
--- a/HISTORY.txt
+++ b/HISTORY.txt
@@ -1,12 +1,8 @@
-================
-oaipmh changelog
-================
-
-Changes
--------
+Changelog
+=========
 
 2.4.3 (2010-08-19)
-==================
+~~~~~~~~~~~~~~~~~~
 
 Changes
 -------
@@ -16,7 +12,7 @@ Changes
     objects get pickled. (lp #617439)
 
 2.4.2 (2010-05-03)
-==================
+~~~~~~~~~~~~~~~~~~
 
 Changes
 -------
@@ -26,7 +22,7 @@ Changes
 
     
 2.4.1 (2009-11-16)
-==================
+~~~~~~~~~~~~~~~~~~
 
 Changes
 -------
@@ -35,7 +31,7 @@ Changes
    default to 23:59:59 instead of 00:00:00
 
 2.4 (2009-05-04)
-================
+~~~~~~~~~~~~~~~~
 
 Changes
 -------
@@ -44,14 +40,15 @@ Changes
   added 'toolkit' description by default.
 
 2.3.1 (2009-04-24)
-================
+~~~~~~~~~~~~~~~~~~
 
 Changes
 -------
 
 * Raise correct error when from and until parameters have different granularities
+
 2.3 (2009-04-23)
-================
+~~~~~~~~~~~~~~~~
 
 Changes
 -------
@@ -77,7 +74,7 @@ Changes
     $ bin/devpython
 
 2.2.1 (2008-04-04)
-================
+~~~~~~~~~~~~~~~~~~
 
 Changes
 -------
@@ -89,7 +86,7 @@ Changes
 * Fix for client code that handles 503 response from server.
 
 2.2 (2006-11-20)
-================
+~~~~~~~~~~~~~~~~
 
 Changes
 -------
@@ -100,17 +97,17 @@ Changes
   efficiently implement batching OAI servers on top of relational
   databases.
 
-* Make it possible to explicitly pass None as the from_ or until parameters
+* Make it possible to explicitly pass None as the from or until parameters
   for a OAIPMH client.
 
 * an extra nsmap argument to Server and BatchingServer allows the
-  programmer to specify either namespace prefix -> namespace URI mappings
+  programmer to specify either namespace prefix to namespace URI mappings
   that should be used in the server output.
 
 * fixed a bug where the output wasn't encoded properly as UTF-8.
 
 2.1.5 (2006-09-18)
-==================
+~~~~~~~~~~~~~~~~~~
 
 Changes
 -------
@@ -118,7 +115,7 @@ Changes
 * compatibility fix: it should work with lxml 1.1 now.
 
 2.1.4 (2006-06-16)
-==================
+~~~~~~~~~~~~~~~~~~
 
 Changes
 -------
@@ -126,7 +123,7 @@ Changes
 * Distribute as an egg.
 
 2.1.3
-=====
+~~~~~
 
 Changes
 -------
@@ -141,7 +138,7 @@ Changes
 * Split off datestamp handling into separate datestamp module.
 
 2.0
-===
+~~~
 
 Changes
 -------
@@ -153,7 +150,7 @@ Changes
   client will make sure only YYYY-MM-DD timestamps are sent.
 
 2.0b1
-=====
+~~~~~
 
 Changes
 -------
@@ -176,7 +173,7 @@ Changes
   list by using list() on them, however.
 
 1.0.1 
-=====
+~~~~~
 
 Bugs fixed
 ----------
@@ -184,7 +181,7 @@ Bugs fixed
 * Typo in oaipmh.py
 
 1.0
-===
+~~~
 
 Bugs fixed
 ----------
@@ -193,12 +190,12 @@ Bugs fixed
   unicode bug.
 
 0.7.4
-=====
+~~~~~
 
 Bugs fixed
 ----------
 
-* A harvest can return records with <header status="deleted"> that
+* A harvest can return records with <header status~"deleted"> that
   contain no metadata and are merely an indication that that
   metadata-set for that resource is no longer on the OAI service.
   These records should be used to remove metadata from the catalog if
@@ -206,6 +203,6 @@ Bugs fixed
   themselves. They aren't now. (Fixed in zope/OAICore/core.py)
 
 0.7 
-===
+~~~
 
 Initial public release.
diff --git a/README.txt b/README.txt
index f1da8f9..31fd2e6 100644
--- a/README.txt
+++ b/README.txt
@@ -1,4 +1,4 @@
-oaipmh
+OAIPMH
 ======
 
 The oaipmh module is a Python implementation of an "Open Archives
@@ -7,4 +7,22 @@ server. The protocol is described here:
 
 http://www.openarchives.org/OAI/openarchivesprotocol.html
 
-See doc/API.txt for a description of the Python API.
+Below is a simple implementation of an OAIPMH client:
+
+>>> from oaipmh.client import Client
+>>> from oaipmh.metadata import MetadataRegistry, oai_dc_reader
+
+>>> URL = 'http://uni.edu/ir/oaipmh'
+
+>>> registry = MetadataRegistry()
+>>> registry.registerReader('oai_dc', oai_dc_reader)
+>>> client = Client(URL, registry)
+
+>>> for record in client.listRecords(metadataPrefix='oai_dc'):
+>>>    print record
+
+
+The pyoai package also contains a generic server implementation of the 
+OAIPMH protocol, this is used as the foundation of the `MOAI Server Platform`_
+
+.. _MOAI Server Platform: http://pypi.python.org/pypi/MOAI