--- a/README.txt	Wed Nov 09 17:06:02 2011 -0800
+++ b/README.txt	Wed Nov 09 19:55:15 2011 -0800
@@ -1,14 +1,46 @@
 fetch
-===========
+=====
 
 fetch stuff from the interwebs
 
+
 Format
 ------
 
-`fetch` fetches from a manifest of the format
+`fetch` fetches from a manifest of the format::
+
+ [URL] [Destination] [Type]
+
+A URL can contain a hash tag (e.g. http://example.com/foo#bar/fleem)
+which is used to extract the subdirectories from a multi-directory
+resource.
+
+The `Type` of the resource is used to dispatch to the included
+Fetchers that take care of fetching the object.  
+
+
+Fetchers
+--------
+
+`fetch` includes several objects for fetching resources::
 
-[URL] [Destination] [Type]
+ file : fetch a single file
+ tar : fetch and extract a tarball
+ hg : checkout a mercurial repository
+ git : checkout a git repository
+
+The `file` fetcher cannot have a hash tag subpath since it is a single
+resource.
+
+Though `fetch` has a set of fetchers included, you can pass an
+arbitrary list into `fetch.Fetch`'s constructor. 
+
+
+Version Control
+---------------
+
+The `hg` and the `git` fetchers fetch from version control systems and
+have additional options.
 
 
 ----