Edits to the intro chapter, and added snippets.

Author: clintongormley

010_Intro/05_What_is_it.asciidoc

@@ -3,7 +3,7 @@ https://lucene.apache.org/core/[Apache Lucene(TM)] , a full-text search engine
 library.  Lucene is arguably the most advanced, performant and fully-featured
 search engine library in existence today -- both open source and proprietary.
 
-But Lucene is just a library. To leverage its power you need to work in Java
+But, Lucene is just a library. To leverage its power you need to work in Java
 and to integrate Lucene directly with your application. Worse, you will likely
 require a degree in Information Retrieval to understand how it works.  Lucene
 is *very* complex.

010_Intro/10_Installing_ES.asciidoc

@@ -1,4 +1,4 @@
-=== Starting Elasticsearch
+=== Installing Elasticsearch
 
 The easiest way to understand what Elasticsearch can do for you is to
 play with it, so let's get started!
@@ -8,7 +8,7 @@ Preferably, you should install the latest version of the official Java
 from http://www.java.com[www.java.com].
 
 You can download the latest version of Elasticsearch from
-http://www.elasticsearch.org/download/.
+http://www.elasticsearch.org/download/[elasticsearch.org/download].
 
 [source,js]
 --------------------------------------------------
@@ -17,22 +17,45 @@ unzip elasticsearch-$VERSION.zip
 cd  elasticsearch-$VERSION
 --------------------------------------------------
 
-Let's also install link:http://www.elasticsearch.org/overview/marvel/[Marvel], a 
-cluster management and monitoring plugin developed by Elasticsearch.  Once 
-installed, all the code snippets in this book will display a _"View in Sense"_ link.
-Clicking this link will load the code into Sense -- an interactive console
-inside of Marvel -- and allow you to follow the example using your Elasticsearch
-installation.  
+TIP: When installing Elasticsearch in production, you can use the method
+described above, or the Debian or RPM packages provided on the
+http://www.elasticsearch.org/downloads[downloads page]. You can also use
+the officially supported
+https://github.com/elasticsearch/puppet-elasticsearch[Puppet module] or
+https://github.com/elasticsearch/cookbook-elasticsearch[Chef cookbook].
 
-Loading samples in Sense will allow you to play with live data and searches, 
-fiddle with parameters and generally make the book much more interactive.
+[[marvel]]
+==== Installing Marvel
 
-[source,js]
+http://www.elasticsearch.com/marvel[Marvel] is a management and monitoring
+tool for Elasticsearch which is free for develoment use. It comes with an
+interactive console called Sense which makes it very easy to talk to
+Elasticsearch directly from your browser.
+
+Many of the code examples in this book include a ``View in Sense'' link. When
+clicked, it will open up a working example of the code in the Sense console.
+You do not have to install Marvel, but it will make this book much more
+interactive by allowing you to  experiment with the code samples on your local
+Elasticsearch cluster.
+
+Marvel is available as a plugin. To download and install it, run this command
+in the Elasticsearch directory:
+
+[source,sh]
 --------------------------------------------------
 ./bin/plugin -i elasticsearch/marvel/latest
+--------------------------------------------------
+
+You probably don't want Marvel to monitor your local cluster, so you can
+disable data collection with this command:
+
+[source,sh]
+--------------------------------------------------
 echo 'marvel.agent.enabled: false' >> ./config/elasticsearch.yml
 --------------------------------------------------
 
+=== Running Elasticsearch
+
 Elasticsearch is now ready to run. You can start it up in the foreground
 with:
 
@@ -58,12 +81,13 @@ You should see a response like this:
    "status": 200,
    "name": "Shrunken Bones",
    "version": {
-      "number": "1.0.0",
-      "lucene_version": "4.6.1"
+      "number": "1.1.0",
+      "lucene_version": "4.7"
    },
    "tagline": "You Know, for Search"
 }
 --------------------------------------------------
+// SENSE: 010_Intro/10_Info.json
 
 This means that your Elasticsearch _cluster_ is up and running, and we can
 start experimenting with it.

010_Intro/15_API.asciidoc

@@ -61,13 +61,13 @@ curl -XGET 'http://localhost:9200/_count?pretty' -d '
 }
 '
 --------------------------------------------------
-<1> The appropriate HTTP method or ``verb'': `GET`, `POST`, `PUT`, `HEAD` or
+<1> The appropriate HTTP _method_ or _verb_: `GET`, `POST`, `PUT`, `HEAD` or
     `DELETE`
 <2> The protocol, hostname and port of any node in the cluster.
 <3> The path of the request.
 <4> Any optional query string parameters, eg `?pretty` will _pretty-print_
-    the JSON response to make it easier to read
-<5> A JSON encoded request body (if the request needs one)
+    the JSON response to make it easier to read.
+<5> A JSON encoded request body (if the request needs one).
 
 Elasticsearch returns an HTTP status code like `200 OK` and (except for `HEAD`
 requests) a JSON encoded response body. The above `curl` request would respond
@@ -120,5 +120,8 @@ GET /_count
     }
 }
 --------------------------------------------------
+// SENSE: 010_Intro/15_Count.json
 
-TODO: Link to the Sense plugin?
+In fact, this is the same format that is used by the Sense console that we
+installed with <<marvel,Marvel>>. You can open and run this code example in
+Sense by clicking the ``View in Sense'' link above.

010_Intro/20_Document.asciidoc

@@ -1,8 +1,8 @@
 === Document oriented
 
 Objects in an application are seldom just a simple list of keys and values.
-More often than not they are complex data structures which may contain other
-dates, geo-locations, objects, or arrays of values.
+More often than not they are complex data structures which may contain dates,
+geo-locations, objects, or arrays of values.
 
 Sooner or later you're going to want to store these objects in a database.
 Trying to do this with the rows and columns of a relational database is the
@@ -13,17 +13,18 @@ retrieve it.
 
 Elasticsearch is _document oriented_, meaning that it stores entire objects or
 _documents_.  Not only does it store them, it also *indexes* the contents of
-each document. In Elasticsearch, you index, search, sort and filter
-documents... not rows of columnar data.  This is a fundamentally different
-way of thinking about data and is one of the reasons Elasticsearch can
-perform complex full text search.
+each document in order to make them searchable. In Elasticsearch, you index,
+search, sort and filter documents... not rows of columnar data.  This is a
+fundamentally different way of thinking about data and is one of the reasons
+Elasticsearch can perform complex full text search.
 
 ==== JSON
 
-Elasticsearch uses _JSON_ (or JavaScript Object Notation ) as the
-serialization format for documents. JSON serialization is supported by most
-programming languages, and has become the standard format used by the NoSQL
-movement. It is simple, concise and easy to read.
+Elasticsearch uses http://en.wikipedia.org/wiki/Json[_JSON_] (or JavaScript
+Object Notation ) as the serialization format for documents. JSON
+serialization is supported by most programming languages, and has become the
+standard format used by the NoSQL movement. It is simple, concise and easy to
+read.
 
 Consider this JSON document which represents a user object:
 
@@ -51,10 +52,10 @@ a flat table structure.
 **************************************************
 
 Almost all languages have modules which will convert arbitrary  data
-structures into JSON for you, but the details are specific  to each language.
-Look for modules which handle JSON __ ``serialization'' __
-or __ ``marshalling'' __.
-http://www.elasticsearch.org/guide[The official Elasticsearch clients] all
-handle conversion to and from JSON for you automatically.
+structures or objects into JSON for you, but the details are specific  to each
+language. Look for modules which handle JSON __ ``serialization'' __ or __
+``marshalling'' __. http://www.elasticsearch.org/guide[The official
+Elasticsearch clients] all handle conversion to and from JSON for you
+automatically.
 
 **************************************************