Revised readme per peer-review

diff --git a/README.md b/README.md
index 0d62a7b..509eb18 100644
--- a/README.md
+++ b/README.md

@@ -8,6 +8,23 @@
 [![GoDoc](https://godoc.org/github.com/pelletier/go-toml?status.svg)](http://godoc.org/github.com/pelletier/go-toml)
 [![Build Status](https://travis-ci.org/pelletier/go-toml.svg?branch=master)](https://travis-ci.org/pelletier/go-toml)
 
+## Features
+
+Go-toml provides the following features for using data parsed from TOML documents:
+
+* Load TOML documents from files and string data
+* Easily navigate TOML structure using TomlTree
+* Line & column position data for all parsed elements
+* Query support similar to JSON-Path
+* Syntax errors contain line and column numbers
+
+Go-toml is designed to help cover use-cases not covered by reflection-based TOML parsing:
+
+* Semantic evaluation of parsed TOML
+* Informing a user of mistakes in the source document, after it has been parsed
+* Programatic handling of default values on a case-by-case basis
+* Using a TOML document as a flexible data-store
+
 ## Import
 
     import "github.com/pelletier/go-toml"
@@ -45,70 +62,22 @@
     user = configTree.Get("user").(string)
     password = configTree.Get("password").(string)
     fmt.Println("User is ", user, ". Password is ", password)
-}
-```
 
-### Dealing with values
+    // show where elements are in the file
+    fmt.Println("User position: %v", configTree.GetPosition("user"))
+    fmt.Println("Password position: %v", configTree.GetPosition("password"))
 
-Here are some important functions you need to know in order to work with the
-values in a TOML tree:
-
-* `tree.Get("comma.separated.path")` Returns the value at the given path in the
-  tree as an `interface{}`. It's up to you to cast the result into the right
-  type.
-* `tree.Set("comma.separated.path", value)` Sets the value at the given path in
-  the tree, creating all necessary intermediate subtrees.
-
-### Dealing with positions
-
-Since
-[e118479061](https://github.com/pelletier/go-toml/commit/e1184790610b20d0541fc9f57c181cc5b1fc78be),
-go-toml supports positions. This feature allows you to track the positions of
-the values inside the source document, for example to provide better feedback in
-your application. Using positions works much like values:
-
-* `tree.GetPosition("comma.separated.path")` Returns the position of the given
-  path in the source.
-
-### Support for queries
-:
-Go-toml also supports a JSON-Path style syntax for querying a document for
-collections of elements, and more.
-
-```go
-import (
-    "fmt"
-    "github.com/pelletier/go-toml"
-)
-config, err := toml.Load(`
-[[book]]
-title = "The Stand"
-author = "Stephen King"
-[[book]]
-title = "For Whom the Bell Tolls"
-author = "Earnest Hemmingway"
-[[book]]
-title = "Neuromancer"
-author = "William Gibson"
-`)
-
-if err != nil {
-    fmt.Println("Error ", err.Error())
-} else {
-    // find and print all the authors in the document
-    authors := config.Query("$.book.author")
-    for _, name := authors.Value() {
-        fmt.Println(name)
+    // use a query to gather elements without walking the tree
+    results, _ := config.Query("$..[user,password]")
+    for ii, item := range results.Values() {
+      fmt.Println("Query result %d: %v", ii, item)
     }
 }
 ```
 
-More information about the format of TOML queries can be found on the
-[godoc page for go-toml](http://godoc.org/github.com/pelletier/go-toml).
-
 ## Documentation
 
-The documentation is available at
+The documentation and additional examples are available at
 [godoc.org](http://godoc.org/github.com/pelletier/go-toml).
 
 ## Contribute

diff --git a/doc_test.go b/doc_test.go
index c5c27a0..7c0e677 100644
--- a/doc_test.go
+++ b/doc_test.go

@@ -2,7 +2,9 @@
 
 package toml
 
-import "fmt"
+import (
+	"fmt"
+)
 
 func ExampleNodeFilterFn_filterExample() {
 	tree, _ := Load(`
@@ -49,3 +51,31 @@
 		fmt.Println(name)
 	}
 }
+
+func Example_comprehensiveExample() {
+	config, err := LoadFile("config.toml")
+
+	if err != nil {
+		fmt.Println("Error ", err.Error())
+	} else {
+		// retrieve data directly
+		user := config.Get("postgres.user").(string)
+		password := config.Get("postgres.password").(string)
+
+		// or using an intermediate object
+		configTree := config.Get("postgres").(*TomlTree)
+		user = configTree.Get("user").(string)
+		password = configTree.Get("password").(string)
+		fmt.Println("User is ", user, ". Password is ", password)
+
+		// show where elements are in the file
+		fmt.Println("User position: %v", configTree.GetPosition("user"))
+		fmt.Println("Password position: %v", configTree.GetPosition("password"))
+
+		// use a query to gather elements without walking the tree
+		results, _ := config.Query("$..[user,password]")
+		for ii, item := range results.Values() {
+			fmt.Println("Query result %d: %v", ii, item)
+		}
+	}
+}