Cleans up the documents.

website/source/docs/agent/http/query.html.markdown

@@ -15,7 +15,7 @@ Prepared queries allow you to register a complex service query and then execute
 it later via its ID or name to get a set of healthy nodes that provide a given
 service. This is particularly useful in combination with Consul's
 [DNS Interface](/docs/agent/dns.html) as it allows for much richer queries than
-would be possible given the limited syntax DNS provides.
+would be possible given the limited entry points exposed by DNS.
 
 The following endpoints are supported:
 
@@ -45,12 +45,11 @@ The general query endpoint supports the `POST` and `GET` methods.
 When using the `POST` method, Consul will create a new prepared query and return
 its ID if it is created successfully.
 
-By default, the datacenter of the agent is queried; however, the dc can be
+By default, the datacenter of the agent is queried; however, the `dc` can be
 provided using the "?dc=" query parameter.
 
-If ACLs are enabled, then the client will need to supply a token with `query`
-write privileges sufficient to match the service name being queried and the `Name`
-given to the query, if any. See also the note about the `Token` field below.
+If ACLs are enabled, the client will need to supply an ACL Token with `query`
+write privileges for the `Name` of the query being created.
 
 The create operation expects a JSON request body that defines the prepared query,
 like this example:
@@ -86,12 +85,13 @@ given session is invalidated. This is optional, and if not given the prepared
 query must be manually removed when no longer needed.
 
 <a name="token"></a>
-`Token` is a captured ACL Token to use when the query is executed. This allows
-queries to be executed by clients with lesser or even no ACL Token, so this
-should be used with care. The token itself can only be seen by clients with a
-management token. If the `Token` field is left blank, the client's ACL Token
-will be used to determine if they have access to the service being queried. If
-the client does not supply an ACL Token, the anonymous token will be used.
+`Token`, if specified, is a captured ACL Token that is reused as the ACL Token
+every time the query is executed. This allows queries to be executed by clients
+with lesser or even no ACL Token, so this should be used with care. The token
+itself can only be seen by clients with a management token. If the `Token`
+field is left blank or omitted, the client's ACL Token will be used to determine
+if they have access to the service being queried. If the client does not supply
+an ACL Token, the anonymous token will be used.
 
 Note that Consul version 0.6.3 and earlier would automatically capture the ACL
 Token for use in the future when prepared queries were executed and would
@@ -161,7 +161,7 @@ a JSON body:
 
 When using the GET method, Consul will provide a listing of all prepared queries.
 
-By default, the datacenter of the agent is queried; however, the dc can be
+By default, the datacenter of the agent is queried; however, the `dc` can be
 provided using the "?dc=" query parameter. This endpoint supports blocking
 queries and all consistency modes.
 
@@ -208,12 +208,11 @@ The query-specific endpoint supports the `GET`, `PUT`, and `DELETE` methods. The
 
 The `PUT` method allows an existing prepared query to be updated.
 
-By default, the datacenter of the agent is queried; however, the dc can be
+By default, the datacenter of the agent is queried; however, the `dc` can be
 provided using the "?dc=" query parameter.
 
-If ACLs are enabled, then the client will need to supply a token with `query`
-write privileges sufficient to match the service name being queried and the `Name`
-given to the query, if any.
+If ACLs are enabled, the client will need to supply an ACL Token with `query`
+write privileges for the `Name` of the query being updated.
 
 The body is the same as is used to create a prepared query, as described above.
 
@@ -223,7 +222,7 @@ If the API call succeeds, a 200 status code is returned.
 
 The `GET` method allows an existing prepared query to be fetched.
 
-By default, the datacenter of the agent is queried; however, the dc can be
+By default, the datacenter of the agent is queried; however, the `dc` can be
 provided using the "?dc=" query parameter. This endpoint supports blocking
 queries and all consistency modes.
 
@@ -240,12 +239,11 @@ management token is used.
 
 The `DELETE` method is used to delete a prepared query.
 
-By default, the datacenter of the agent is queried; however, the dc can be
+By default, the datacenter of the agent is queried; however, the `dc` can be
 provided using the "?dc=" query parameter.
 
-If ACLs are enabled, then the client will need to supply a token with `query`
-write privileges sufficient to match the service name being queried and the `Name`
-given to the query, if any.
+If ACLs are enabled, the client will need to supply an ACL Token with `query`
+write privileges for the `Name` of the query being deleted.
 
 No body is required as part of this request.
 
@@ -257,7 +255,7 @@ The query execute endpoint supports only the `GET` method and is used to
 execute a prepared query. The \<query or name\> argument is the ID or name
 of an existing prepared query.
 
-By default, the datacenter of the agent is queried; however, the dc can be
+By default, the datacenter of the agent is queried; however, the `dc` can be
 provided using the "?dc=" query parameter. This endpoint does not support
 blocking queries, but it does support all consistency modes.
 

website/source/docs/internals/acl.html.markdown

@@ -348,11 +348,6 @@ service, then the DNS interface will return no records when queried for it.
 <a name="prepared_query_acls"></a>
 ## Prepared Query ACLs
 
-Prepared queries have a more complicated relationship with ACLs than most other
-Consul resources because they have a lifecycle related to creating, reading,
-updating, and deleting queries, and then a separate lifecycle related to
-executing queries.
-
 As we've gotten feedback from Consul users, we've evolved how prepared queries
 use ACLs. In this section we first cover the current implementation, and then we
 follow that with details about what's changed between specific versions of Consul.
@@ -381,17 +376,16 @@ These variations are covered here, with examples:
   way to define more specific policies. Clients can list or read queries for
   which they have "read" access based on their prefix, and similar they can
   update any queries for which they have "write" access. An example use for
-  this type is a query with a well-known name (eg. prod-master-customer-db)
+  this type is a query with a well-known name (eg. `prod-master-customer-db`)
   that is used and known by many clients to provide geo-failover behavior for
   a database.
 
 #### Executing Pepared Queries
 
-When prepared queries are executed via DNS lookups or HTTP requests, the
-management ACL isn't used in any way. Instead, ACLs are applied to the service
-being queried, similar to how other service lookups work, except that prepared
-queries have some special behavior related to where the ACL Token comes
-from:
+When prepared queries are executed via DNS lookups or HTTP requests, the ACL
+checks are run against the service being queried, similar to how ACLs work with
+other service lookups. There are several ways the ACL token is selected for this
+check:
 
 * If an ACL Token was captured when the prepared query was defined, it will be
   used to perform the service lookup. This allows queries to be executed by
@@ -400,9 +394,14 @@ from:
 * If no ACL Token was captured, then the client's ACL Token will be used to
   perform the service lookup.
 
-* If no ACL Token was captured, and the client has no ACL Token, then the
+* If no ACL Token was captured and the client has no ACL Token, then the
   anonymous token will be used to perform the service lookup.
 
+In the common case, the ACL Token of the invoker is used
+to test the ability to look up a service. If a `Token` was specified when the
+prepared query was created, the behavior changes and now the captured
+ACL Token set by the definer of the query is used when lookup up a service.
+
 Capturing ACL Tokens is analogous to
 [PostgreSQL’s](http://www.postgresql.org/docs/current/static/sql-createfunction.html)
 `SECURITY DEFINER` attribute which can be set on functions, and using the client's ACL