Clarify enable_tag_override explanation

In designing a potential UI for a configuration of `enable_tag_override`,
I found the documentation confusing and lengthy. Here, I've made an
attempt at re-writing this section to be more concise and clear.

I also made a few small changes to the organization of this file to map
explanations to the order of the properties listing at the top. I find
it easier to scan docs when explanations appear in the same order they
are listed at the top. For explanations that span multiple paragraphs, I
provided a subheading, which also helps in linking from other pages.

Finally, I removed a duplicated paragraph from the documentation.

website/source/docs/agent/services.html.md

@@ -62,15 +62,11 @@ example shows all possible fields, but note that only a few are required.
 ```
 
 A service definition must include a `name` and may optionally provide an
-`id`, `tags`, `address`, `port`, `check`, `meta` and `enable_tag_override`.
+`id`, `tags`, `address`, `meta`, `port`, `enable_tag_override`,  and `check`.
 The `id` is set to the `name` if not provided. It is required that all
 services have a unique ID per node, so if names might conflict then
 unique IDs should be provided.
 
-For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0
-supports both `enable_tag_override` and `enableTagOverride` but the latter is
-deprecated and has been removed in Consul 1.1.
-
 The `tags` property is a list of values that are opaque to Consul but
 can be used to distinguish between `primary` or `secondary` nodes,
 different versions, or any other service level labels.
@@ -89,9 +85,37 @@ meta object in node definition.
 All those meta data can be retrieved individually per instance of the service
 and all the instances of a given service have their own copy of it.
 
-Services may also contain a `token` field to provide an ACL token. This token is
-used for any interaction with the catalog for the service, including
-[anti-entropy syncs](/docs/internals/anti-entropy.html) and deregistration.
+The `kind` field is used to optionally identify the service as an [unmanaged
+Connect proxy](/docs/connect/proxies.html#unmanaged-proxies) instance with the
+value `connect-proxy`. For typical non-proxy instances the `kind` field must be
+omitted. The `proxy_destination` field is also required for unmanaged proxy
+registrations and is only valid if `kind` is `connect-proxy`. It's value must be
+the _name_ of the service that the proxy is handling traffic for.
+
+The `connect` field can be specified to configure
+[Connect](/docs/connect/index.html) for a service. This field is available in
+Consul 1.2 and later. The `native` value can be set to true to advertise the
+service as [Connect-native](/docs/connect/native.html). If the `proxy` field is
+set (even to an empty object), then this will enable a [managed
+proxy](/docs/connect/proxies.html) for the service. The fields within `proxy`
+are used to configure the proxy and are specified in the [proxy
+docs](/docs/connect/proxies.html). If `native` is true, it is an error to also
+specifiy a managed proxy instance.
+
+The `weights` field is an optional field to specify the weight of a service in
+DNS SRV responses. If this field is not specified, its default value is:
+`"weights": {"passing": 1, "warning": 1}`.
+When a service is `critical`, it is excluded from DNS responses.
+Services with warning checks are in included in responses by default,
+but excluded if the optional param `only_passing = true` is present in
+agent DNS configuration or `?passing` is used via the API.
+When DNS SRV requests are made, the response will include the weights
+specified given the state of the service.
+This allows some instances to be given higher weight if they have more capacity,
+and optionally allows reducing load on services with checks in `warning` status
+by giving passing instances a higher weight.
+
+### Checks
 
 A service can have an associated health check. This is a powerful feature as
 it allows a web balancer to gracefully remove failing nodes, a database
@@ -111,19 +135,19 @@ from `1`.
 
 -> **Note:** There is more information about [checks here](/docs/agent/checks.html).
 
-The `enable_tag_override` can optionally be specified to disable the
-anti-entropy feature for this service. If `enable_tag_override` is set to
-`TRUE` then external agents can update this service in the
-[catalog](/api/catalog.html) and modify the tags. Subsequent
-local sync operations by this agent will ignore the updated tags. For
-example, if an external agent modified both the tags and the port for
-this service and `enable_tag_override` was set to `TRUE` then after the next
-sync cycle the service's port would revert to the original value but the
-tags would maintain the updated value. As a counter example: If an
-external agent modified both the tags and port for this service and
-`enable_tag_override` was set to `FALSE` then after the next sync cycle the
-service's port *and* the tags would revert to the original value and all
-modifications would be lost.
+### Enable Tag Override and Anti-Entropy
+
+Services may also contain a `token` field to provide an ACL token. This token is
+used for any interaction with the catalog for the service, including
+[anti-entropy syncs](/docs/internals/anti-entropy.html) and deregistration.
+
+You can optionally disable the anti-entropy feature for this service using the
+`enable_tag_override` flag. External agents can modify tags on services in the
+catalog, so subsequent sync operations can either maintain tag modifications or
+revert them. If `enable_tag_override` is set to `TRUE`, the next sync cycle may
+revert some service properties, **but** the tags would maintain the updated value.
+If `enable_tag_override` is set to `FALSE`, the next sync cycle will revert any
+updated service properties, **including** tags, to their original value.
 
 It's important to note that this applies only to the locally registered
 service. If you have multiple nodes all registering the same service
@@ -138,36 +162,6 @@ For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0
 supports both `enable_tag_override` and `enableTagOverride` but the latter is
 deprecated and has been removed as of Consul 1.1.
 
-The `kind` field is used to optionally identify the service as an [unmanaged
-Connect proxy](/docs/connect/proxies.html#unmanaged-proxies) instance with the
-value `connect-proxy`. For typical non-proxy instances the `kind` field must be
-omitted. The `proxy_destination` field is also required for unmanaged proxy
-registrations and is only valid if `kind` is `connect-proxy`. It's value must be
-the _name_ of the service that the proxy is handling traffic for.
-
-The `connect` field can be specified to configure
-[Connect](/docs/connect/index.html) for a service. This field is available in
-Consul 1.2 and later. The `native` value can be set to true to advertise the
-service as [Connect-native](/docs/connect/native.html). If the `proxy` field is
-set (even to an empty object), then this will enable a [managed
-proxy](/docs/connect/proxies.html) for the service. The fields within `proxy`
-are used to configure the proxy and are specified in the [proxy
-docs](/docs/connect/proxies.html). If `native` is true, it is an error to also
-specifiy a managed proxy instance.
-
-The `weights` field is an optional field to specify the weight of a service in
-DNS SRV responses. If this field is not specified, its default value is:
-`"weights": {"passing": 1, "warning": 1}`.
-When a service is `critical`, it is excluded from DNS responses.
-Services with warning checks are in included in responses by default,
-but excluded if the optional param `only_passing = true` is present in
-agent DNS configuration or `?passing` is used via the API.
-When DNS SRV requests are made, the response will include the weights
-specified given the state of the service.
-This allows some instances to be given higher weight if they have more capacity,
-and optionally allows reducing load on services with checks in `warning` status
-by giving passing instances a higher weight.
-
 ## Multiple Service Definitions
 
 Multiple services definitions can be provided at once using the plural

website/source/docs/internals/anti-entropy.html.md

@@ -136,7 +136,7 @@ If an error is encountered during an anti-entropy run, the error is logged and
 the agent continues to run. The anti-entropy mechanism is run periodically to
 automatically recover from these types of transient failures.
 
-### EnableTagOverride
+### Enable Tag Override
 
 Synchronization of service registration can be partially modified to
 allow external agents to change the tags for a service. This can be
@@ -146,7 +146,7 @@ database and its monitoring service Redis Sentinel have this kind of
 relationship. Redis instances are responsible for much of their
 configuration, but Sentinels determine whether the Redis instance is a
 primary or a secondary. Using the Consul service configuration item
-[EnableTagOverride](/docs/agent/services.html) you can instruct the
+[enable_tag_override](/docs/agent/services.html) you can instruct the
 Consul agent on which the Redis database is running to NOT update the
 tags during anti-entropy synchronization. For more information see
-[Services](/docs/agent/services.html) page.
+[Services](/docs/agent/services.html#enable-tag-override-and-anti-entropy) page.