Tidied up the update docs

Closes #9459

docs/reference/docs/update.asciidoc

@@ -23,6 +23,9 @@ curl -XPUT localhost:9200/test/type1/1 -d '{
 }'
 --------------------------------------------------
 
+[float]
+=== Scripted updates
+
 Now, we can execute a script that would increment the counter:
 
 [source,js]
@@ -37,7 +40,7 @@ curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
 }'
 --------------------------------------------------
 
-We can also add a tag to the list of tags (note, if the tag exists, it
+We can add a tag to the list of tags (note, if the tag exists, it
 will still add it, since its a list):
 
 [source,js]
@@ -52,6 +55,10 @@ curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
 }'
 --------------------------------------------------
 
+In addition to `_source`, the following variables are available through
+the `ctx` map: `_index`, `_type`, `_id`, `_version`, `_routing`,
+`_parent`, `_timestamp`, `_ttl`.
+
 We can also add a new field to the document:
 
 [source,js]
@@ -61,7 +68,7 @@ curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
 }'
 --------------------------------------------------
 
-We can also remove a field from the document:
+Or remove a field from the document:
 
 [source,js]
 --------------------------------------------------
@@ -70,7 +77,9 @@ curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
 }'
 --------------------------------------------------
 
-And, we can delete the doc if the tags contain blue, or ignore (noop):
+And, we can even change the operation that is executed.  This example deletes
+the doc if the `tags` field contain `blue`, otherwise it does nothing
+(`noop`):
 
 [source,js]
 --------------------------------------------------
@@ -84,19 +93,8 @@ curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
 }'
 --------------------------------------------------
 
-*Note*: Be aware of MVEL and handling of ternary operators and
-assignments. Assignment operations have lower precedence than the
-ternary operator. Compare the following statements:
-
-[source,js]
---------------------------------------------------
-// Will NOT update the tags array
-ctx._source.tags.contains(tag) ? ctx.op = \"none\" : ctx._source.tags += tag
-// Will update
-ctx._source.tags.contains(tag) ? (ctx.op = \"none\") : ctx._source.tags += tag
-// Also works
-if (ctx._source.tags.contains(tag)) { ctx.op = \"none\" } else { ctx._source.tags += tag }
---------------------------------------------------
+[float]
+=== Updates with a partial document
 
 The update API also support passing a partial document,
 which will be merged into the existing document (simple recursive merge,
@@ -115,10 +113,14 @@ curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
 If both `doc` and `script` is specified, then `doc` is ignored. Best is
 to put your field pairs of the partial document in the script itself.
 
+[float]
+=== `detect_noop`
+
 By default if `doc` is specified then the document is always updated even
 if the merging process doesn't cause any changes.  Specifying `detect_noop`
 as `true` will cause Elasticsearch to check if there are changes and, if
 there aren't, turn the update request into a noop. For example:
+
 [source,js]
 --------------------------------------------------
 curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
@@ -135,9 +137,10 @@ request is ignored.
 [[upserts]]
 [float]
 === Upserts
-There is also support for `upsert`. If the document does
-not already exists, the content of the `upsert` element will be used to
-index the fresh doc:
+
+If the document does not already exist, the contents of the `upsert` element
+will be inserted as a new document.  If the document does exist, then the
+`script` will be executed instead:
 
 [source,js]
 --------------------------------------------------
@@ -153,10 +156,13 @@ curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
     }
 }'
 --------------------------------------------------
-If the document does not exist you may want your update script to
-run anyway in order to initialize the document contents using 
-business logic unknown to the client. In this case pass the
-new `scripted_upsert` parameter with the value `true`. 
+
+[float]
+==== `scripted_upsert`
+
+If you would like your script to run regardless of whether the document exists
+or not -- i.e. the script handles initializing the document instead of the
+`upsert` element -- then set `scripted_upsert` to `true`:
 
 [source,js]
 --------------------------------------------------
@@ -172,22 +178,16 @@ curl -XPOST 'localhost:9200/sessions/session/dh3sgudg8gsrgl/_update' -d '{
             }
         }
     },
-    "upsert" : {
-    }
+    "upsert" : {}
 }'
 --------------------------------------------------
-The default `scripted_upsert` setting is `false` meaning the script is not executed for inserts.
-However, in scenarios like the one above we may be using a non-trivial script stored
-using the new "indexed scripts" feature. The script may be deriving properties 
-like the duration of our web session based on observing multiple page view events so the 
-client can supply a blank "upsert" document and allow the script to fill in most of the details
-using the events passed in the `params` element.  
 
+[float]
+==== `doc_as_upsert`
 
-Last, the upsert facility also supports `doc_as_upsert`. So that the
-provided document will be inserted if the document does not already
-exist. This will reduce the amount of data that needs to be sent to
-elasticsearch.
+Instead of sending a partial `doc` plus an `upsert` doc, setting
+`doc_as_upsert` to `true` will use the contents of `doc` as the `upsert`
+value:
 
 [source,js]
 --------------------------------------------------
@@ -203,50 +203,56 @@ curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
 [float]
 === Parameters
 
-The update operation supports similar parameters as the index API,
-including:
+The update operation supports the following query-string parameters:
 
 [horizontal]
-`routing`::     Routing is used to route the update request to the right shard
-                and sets the routing for the upsert request if the document being
-                updated doesn't exist. Can't be used to update the routing of an
-                existing document.
-
-`parent`::      Parent is used to route the update request to the right shard
-                and sets the parent for the upsert request if the document being
-                updated doesn't exist. Can't be used to update the `parent` of an
-                existing document.
-
-`timeout`::     Timeout waiting for a shard to become available.
-
-`consistency`:: The write consistency of the index/delete operation.
-
-`refresh`::     Refresh the relevant primary and replica shards (not the whole
-                index) immediately after the operation occurs, so that the
-                updated document appears in search results  immediately.
-
-`fields`::      return the relevant fields from the updated document.
-                Support `_source` to return the full updated 
-                source.
-
-`version` & `version_type`:: the Update API uses the Elasticsearch's versioning
-                support internally to make sure the document doesn't change
-                during the update. You can use the `version` parameter to specify that the
-                document should only be updated if it's version matches the one specified.
-                By setting version type to `force` you can force the new version of the document
-                after update (use with care! with `force` there is no guarantee the document
-                didn't change).Version types `external` & `external_gte` are not supported.
-
-                
-And also support `retry_on_conflict` which controls how many times to
-retry if there is a version conflict between getting the document and
-indexing / deleting it. Defaults to `0`.
-
-It also allows to update the `ttl` of a document using `ctx._ttl` and
-timestamp using `ctx._timestamp`. Note that if the timestamp is not
-updated and not extracted from the `_source` it will be set to the
-update date.
+`retry_on_conflict`::
+
+In between the get and indexing phases of the update, it is possible that
+another process might have already updated the same document.  By default, the
+update will fail with a version conflict exception.  The `retry_on_conflict`
+parameter controls how many times to retry the update before finally throwing
+an exception.
+
+`routing`::
+
+Routing is used to route the update request to the right shard and sets the
+routing for the upsert request if the document being updated doesn't exist.
+Can't be used to update the routing of an existing document.
+
+`parent`::
+
+Parent is used to route the update request to the right shard and sets the
+parent for the upsert request if the document being updated doesn't exist.
+Can't be used to update the `parent` of an existing document.
+
+`timeout`::
+
+Timeout waiting for a shard to become available.
+
+`consistency`::
+
+The write consistency of the index/delete operation.
+
+`refresh`::
+
+Refresh the relevant primary and replica shards (not the whole index)
+immediately after the operation occurs, so that the updated document appears
+in search results  immediately.
+
+`fields`::
+
+Return the relevant fields from the updated document. Specify `_source` to
+return the full updated source.
+
+`version` & `version_type`::
+
+The Update API uses the Elasticsearch's versioning support internally to make
+sure the document doesn't change during the update. You can use the `version`
+parameter to specify that the document should only be updated if it's version
+matches the one specified. By setting version type to `force` you can force
+the new version of the document after update (use with care! with `force`
+there is no guarantee the document didn't change).Version types `external` &
+`external_gte` are not supported.
+
 
-In addition to `_source`, the following variables are available through
-the `ctx` map: `_index`, `_type`, `_id`, `_version`, `_routing`,
-`_parent`, `_timestamp`, `_ttl`.