updated README to be more snarky

README.md

@@ -1,10 +1,95 @@
-Description
------------
+Overview
+--------
 
 [![Build Status](https://secure.travis-ci.org/edsu/pymarc.png)](http://travis-ci.org/edsu/pymarc)
 
 pymarc is a python library for working with bibliographic data encoded in 
-[MARC21](http://en.wikipedia.org/wiki/MARC_standards).
+[MARC21](http://en.wikipedia.org/wiki/MARC_standards). It provides an API 
+for reading, writing and modifying MARC records. It was mostly designed to 
+be an emergency eject seat, for getting your data assets out of MARC and into
+some kind of saner representation. However over the years it has been used 
+to create and modify MARC records, since repeated calls for it to die as a
+format have resulted in it living happily as a zombie. If you are brand new
+to MARC and need to understand it enough to be able to extract titles, subjects,
+etc from records [Understanding MARC](http://www.loc.gov/marc/umb/) is a 
+useful read.
+
+Below are some common examples of how you might want to use pymarc. If 
+you run across an example that you think should be here please send a 
+pull request.
+
+### Reading
+
+Most often you will have some MARC data and will want to extract data
+from it. Here's an example of reading a batch of records and printing out 
+the 245 subfield a. If you are curious this example uses the batch file 
+available here in pymarc repository:
+
+    >>> from pymarc import MARCReader
+    >>> reader = MARCReader(open('test/marc.dat'))
+    >>> for record in reader: 
+    ...    print record['245']['a']
+    The pragmatic programmer :
+    Programming Python /
+    Learning Python /
+    Python cookbook /
+    Python programming for the absolute beginner /
+    Web programming :
+    Python programming on Win32 /
+    Python programming :
+    Python Web programming /
+    Core python programming /
+    Python and Tkinter programming /
+    Game programming with Python, Lua, and Ruby /
+    Python programming patterns /
+    Python programming with the Java class libraries :
+    Learn to program using Python :
+    Programming with Python /
+    BSD Sockets programming from a multi-language perspective /
+    Design patterns :
+    Introduction to algorithms /
+    ANSI Common Lisp /
+
+
+### Writing
+
+Here's an example of creating a record and writing it out to a file.
+
+    >>> from pymarc import Record, Field
+    >>> record = Record()
+    >>> record.addField(
+    ...     Field(
+    ...         tag = '245', 
+    ...         indicators = ['0','1'],
+    ...         subfields = [
+    ...             'a', 'The pragmatic programmer : ',
+    ...             'b', 'from journeyman to master /', 
+    ...             'c', 'Andrew Hunt, David Thomas.'
+    ...         ]))
+    >>> out = open('file.dat', 'w')
+    >>> out.write(record.asMARC21())
+    >>> out.close()
+
+### Updating
+
+Modifying works the same way, you read it in, modify it, and then write it out
+again:
+
+    >>> from pymarc import MARCReader
+    >>> reader = MARCReader(open('test/marc.dat'))
+    >>> record = reader.next()
+    >>> record['245']['a'] = 'The Zombie Programmer'
+    >>> out = open('file.dat', 'w')
+    >>> out.write(record.asMARC21())
+    >>> out.close()
+
+
+### JSON and XML
+
+If you find yourself using MARC data a fair bit, and distributing it, you may 
+make other developers a bit happier by using the JSON or XML serializations. 
+pymarc has support for both. The main benefit here is that the UTF8 character
+encoding is used, rather than the frustratingly archaic MARC8 encoding.
 
 Installation
 ------------
@@ -26,9 +111,6 @@ And then install:
 
     python setup.py install
 
-For typical usage of this library look at the documentation in 
-pymarc/__init__.py or at the unittests found in the test directory.
-
 Support
 -------