From 039b2ff05223ea93d9a43eaecdd17e43a3d442a7 Mon Sep 17 00:00:00 2001
From: Nathan Reese <reese.nathan@gmail.com>
Date: Fri, 15 Jan 2021 12:45:51 -0700
Subject: [PATCH] [Docs] clean-up vega map reference documenation (#88487)

* [Docs] clean-up vega map reference documenation

* Update docs/user/dashboard/vega-reference.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>
---
 docs/user/dashboard/vega-reference.asciidoc | 58 ++++++++++-----------
 1 file changed, 29 insertions(+), 29 deletions(-)

diff --git a/docs/user/dashboard/vega-reference.asciidoc b/docs/user/dashboard/vega-reference.asciidoc
index d6593143e4f6d..f05d58918a2eb 100644
--- a/docs/user/dashboard/vega-reference.asciidoc
+++ b/docs/user/dashboard/vega-reference.asciidoc
@@ -216,24 +216,8 @@ on the currently picked range: `"interval": {"%autointerval%": 10}` will
 try to get about 10-15 data points (buckets).
 
 [float]
-[[vega-esmfiles]]
-=== Access Elastic Map Service files
-
-experimental[] Access the Elastic Map Service files via the same mechanism:
-
-[source,yaml]
-----
-url: {
-  // "type" defaults to "elasticsearch" otherwise
-  type: emsfile
-  // Name of the file, exactly as in the Region map visualization
-  name: World Countries
-}
-// The result is a geojson file, get its features to use
-// this data source with the "shape" marks
-// https://vega.github.io/vega/docs/marks/shape/
-format: {property: "features"}
-----
+[[vega-with-a-map]]
+=== Vega with a Map
 
 To enable Maps, the graph must specify `type=map` in the host
 configuration:
@@ -282,6 +266,22 @@ Additionally, you can use `latitude`, `longitude`, and `zoom` signals.
 These signals can be used in the graph, or can be updated to modify the
 position of the map.
 
+experimental[] You can use Vega's https://vega.github.io/vega/docs/data/[data] element to access https://www.elastic.co/elastic-maps-service[Elastic Maps Service (EMS)] vector shapes of administrative boundaries in your Vega map by setting `url.data` to `emsFile`:
+
+[source,yaml]
+----
+url: {
+  // "type" defaults to "elasticsearch" otherwise
+  type: emsfile
+  // Name of the file, exactly as in the Region map visualization
+  name: World Countries
+}
+// The result is a geojson file, get its features to use
+// this data source with the "shape" marks
+// https://vega.github.io/vega/docs/marks/shape/
+format: {property: "features"}
+----
+
 [float]
 [[vega-tooltip]]
 ==== Additional tooltip styling
@@ -308,22 +308,22 @@ a configuration option for changing the tooltip position and padding:
 [[vega-url-loading]]
 ==== Advanced setting to enable URL loading from any domain
 
-Vega can load data from any URL, but this is disabled by default in {kib}. 
+Vega can load data from any URL, but this is disabled by default in {kib}.
 To change this, set `vis_type_vega.enableExternalUrls: true` in `kibana.yml`,
 then restart {kib}.
 
 [float]
 [[vega-inspector]]
 ==== Vega Inspector
-Use the contextual *Inspect* tool to gain insights into different elements. 
+Use the contextual *Inspect* tool to gain insights into different elements.
 For Vega visualizations, there are two different views: *Request* and *Vega debug*.
 
 [float]
 [[inspect-elasticsearch-requests]]
 ===== Inspect {es} requests
 
-Vega uses the {ref}/search-search.html[{es} search API] to get documents and aggregation 
-results from {es}. To troubleshoot these requests, click *Inspect*, which shows the most recent requests. 
+Vega uses the {ref}/search-search.html[{es} search API] to get documents and aggregation
+results from {es}. To troubleshoot these requests, click *Inspect*, which shows the most recent requests.
 In case your specification has more than one request, you can switch between the views using the *View* dropdown.
 
 [role="screenshot"]
@@ -333,10 +333,10 @@ image::visualize/images/vega_tutorial_inspect_requests.png[]
 [[vega-debugging]]
 ===== Vega debugging
 
-With the *Vega debug* view, you can inspect the *Data sets* and *Signal Values* runtime data. 
- 
-The runtime data is read from the 
-https://vega.github.io/vega/docs/api/debugging/#scope[runtime scope]. 
+With the *Vega debug* view, you can inspect the *Data sets* and *Signal Values* runtime data.
+
+The runtime data is read from the
+https://vega.github.io/vega/docs/api/debugging/#scope[runtime scope].
 
 [role="screenshot"]
 image::visualize/images/vega_tutorial_inspect_data_sets.png[]
@@ -348,15 +348,15 @@ the <<vega-browser-debugging-console, Vega browser debugging process>>.
 [[asking-for-help-with-a-vega-spec]]
 ===== Asking for help with a Vega spec
 
-Because of the dynamic nature of the data in {es}, it is hard to help you with 
+Because of the dynamic nature of the data in {es}, it is hard to help you with
 Vega specs unless you can share a dataset. To do this, click *Inspect*, select the *Vega debug* view,
 then select the *Spec* tab:
 
 [role="screenshot"]
 image::visualize/images/vega_tutorial_getting_help.png[]
 
-To copy the response, click *Copy to clipboard*. Paste the copied data to 
-https://gist.github.com/[gist.github.com], possibly with a .json extension. Use the [raw] button, 
+To copy the response, click *Copy to clipboard*. Paste the copied data to
+https://gist.github.com/[gist.github.com], possibly with a .json extension. Use the [raw] button,
 and share that when asking for help.
 
 [float]