[DOCS] Add template docs to scripts. Reorder template examples. (#45817)

* [DOCS] Add template docs to scripts. Reorder template examples.

* Adds a 'Search template' section to the 'How to use scripts' chapter.
  This links to the 'Search template' chapter for detailed info and
  examples.

* Reorders and retitles several examples in the 'Search template'
  chapter. This is primarily to make examples for storing, deleting, and
  using search templates more prominent.

* Change <templatename> to <templateid>

docs/reference/scripting/using.asciidoc

@@ -195,6 +195,21 @@ DELETE _scripts/calculate-score
 // CONSOLE
 // TEST[continued]
 
+[float]
+[[modules-scripting-search-templates]]
+=== Search templates
+You can also use the `_scripts` API to store **search templates**. Search
+templates save specific <<search-search,search requests>> with placeholder
+values, called template parameters.
+
+You can use stored search templates to run searches without writing out the
+entire query. Just provide the stored template's ID and the template parameters.
+This is useful when you want to run a commonly used query quickly and without
+mistakes.
+
+Search templates use the http://mustache.github.io/mustache.5.html[mustache
+templating language]. See <<search-template>> for more information and examples.
+
 [float]
 [[modules-scripting-using-caching]]
 === Script caching

docs/reference/search/search-template.asciidoc

@@ -32,7 +32,209 @@ disable scripts per type and context as described in the
 <<allowed-script-types-setting, scripting docs>>
 
 [float]
-==== More template examples
+==== Examples
+
+[float]
+[[pre-registered-templates]]
+===== Store a search template
+
+You can store a search template using the stored scripts API.
+
+[source,js]
+------------------------------------------
+POST _scripts/<templateid>
+{
+    "script": {
+        "lang": "mustache",
+        "source": {
+            "query": {
+                "match": {
+                    "title": "{{query_string}}"
+                }
+            }
+        }
+    }
+}
+------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+//////////////////////////
+
+We want to be sure that the template has been created,
+because we'll use it later.
+
+[source,js]
+--------------------------------------------------
+{
+    "acknowledged" : true
+}
+--------------------------------------------------
+// TESTRESPONSE
+
+//////////////////////////
+
+This template can be retrieved by
+
+[source,js]
+------------------------------------------
+GET _scripts/<templateid>
+------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+which is rendered as:
+
+[source,js]
+------------------------------------------
+{
+    "script" : {
+        "lang" : "mustache",
+        "source" : "{\"query\":{\"match\":{\"title\":\"{{query_string}}\"}}}",
+        "options": {
+          "content_type" : "application/json; charset=UTF-8"
+        }
+    },
+    "_id": "<templateid>",
+    "found": true
+}
+------------------------------------------
+// TESTRESPONSE
+
+This template can be deleted by
+
+[source,js]
+------------------------------------------
+DELETE _scripts/<templateid>
+------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+//////////////////////////
+
+We want to be sure that the template has been created,
+because we'll use it later.
+
+[source,js]
+--------------------------------------------------
+{
+    "acknowledged" : true
+}
+--------------------------------------------------
+// TESTRESPONSE
+
+//////////////////////////
+
+[float]
+[[use-registered-templates]]
+===== Use a stored search template
+
+To use a stored template at search time use:
+
+[source,js]
+------------------------------------------
+GET _search/template
+{
+    "id": "<templateid>", <1>
+    "params": {
+        "query_string": "search for these words"
+    }
+}
+------------------------------------------
+// CONSOLE
+// TEST[catch:missing]
+<1> Name of the stored template script.
+
+[float]
+[[_validating_templates]]
+==== Validate a search template
+
+A template can be rendered in a response with given parameters using
+
+[source,js]
+------------------------------------------
+GET _render/template
+{
+  "source": "{ \"query\": { \"terms\": {{#toJson}}statuses{{/toJson}} }}",
+  "params": {
+    "statuses" : {
+        "status": [ "pending", "published" ]
+    }
+  }
+}
+------------------------------------------
+// CONSOLE
+
+This call will return the rendered template:
+
+[source,js]
+------------------------------------------
+{
+  "template_output": {
+    "query": {
+      "terms": {
+        "status": [ <1>
+          "pending",
+          "published"
+        ]
+      }
+    }
+  }
+}
+------------------------------------------
+// TESTRESPONSE
+<1> `status` array has been populated with values from the `params` object.
+
+Stored templates can also be rendered using
+
+[source,js]
+------------------------------------------
+GET _render/template/<template_name>
+{
+  "params": {
+    "..."
+  }
+}
+------------------------------------------
+// NOTCONSOLE
+
+[float]
+===== Explain
+
+You can use `explain` parameter when running a template:
+
+[source,js]
+------------------------------------------
+GET _search/template
+{
+  "id": "my_template",
+  "params": {
+    "status": [ "pending", "published" ]
+  },
+  "explain": true
+}
+------------------------------------------
+// CONSOLE
+// TEST[catch:missing]
+
+[float]
+===== Profiling
+
+You can use `profile` parameter when running a template:
+
+[source,js]
+------------------------------------------
+GET _search/template
+{
+  "id": "my_template",
+  "params": {
+    "status": [ "pending", "published" ]
+  },
+  "profile": true
+}
+------------------------------------------
+// CONSOLE
+// TEST[catch:missing]
 
 [float]
 ===== Filling in a query string with a single value
@@ -397,204 +599,6 @@ The previous query will be rendered as:
 ------------------------------------------
 // TESTRESPONSE
 
-
-[float]
-[[pre-registered-templates]]
-===== Pre-registered template
-
-You can register search templates by using the stored scripts api.
-
-[source,js]
-------------------------------------------
-POST _scripts/<templatename>
-{
-    "script": {
-        "lang": "mustache",
-        "source": {
-            "query": {
-                "match": {
-                    "title": "{{query_string}}"
-                }
-            }
-        }
-    }
-}
-------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-//////////////////////////
-
-We want to be sure that the template has been created,
-because we'll use it later.
-
-[source,js]
---------------------------------------------------
-{
-    "acknowledged" : true
-}
---------------------------------------------------
-// TESTRESPONSE
-
-//////////////////////////
-
-This template can be retrieved by
-
-[source,js]
-------------------------------------------
-GET _scripts/<templatename>
-------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-which is rendered as:
-
-[source,js]
-------------------------------------------
-{
-    "script" : {
-        "lang" : "mustache",
-        "source" : "{\"query\":{\"match\":{\"title\":\"{{query_string}}\"}}}",
-        "options": {
-          "content_type" : "application/json; charset=UTF-8"
-        }
-    },
-    "_id": "<templatename>",
-    "found": true
-}
-------------------------------------------
-// TESTRESPONSE
-
-This template can be deleted by
-
-[source,js]
-------------------------------------------
-DELETE _scripts/<templatename>
-------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-//////////////////////////
-
-We want to be sure that the template has been created,
-because we'll use it later.
-
-[source,js]
---------------------------------------------------
-{
-    "acknowledged" : true
-}
---------------------------------------------------
-// TESTRESPONSE
-
-//////////////////////////
-
-To use a stored template at search time use:
-
-[source,js]
-------------------------------------------
-GET _search/template
-{
-    "id": "<templateName>", <1>
-    "params": {
-        "query_string": "search for these words"
-    }
-}
-------------------------------------------
-// CONSOLE
-// TEST[catch:missing]
-<1> Name of the stored template script.
-
-[float]
-==== Validating templates
-
-A template can be rendered in a response with given parameters using
-
-[source,js]
-------------------------------------------
-GET _render/template
-{
-  "source": "{ \"query\": { \"terms\": {{#toJson}}statuses{{/toJson}} }}",
-  "params": {
-    "statuses" : {
-        "status": [ "pending", "published" ]
-    }
-  }
-}
-------------------------------------------
-// CONSOLE
-
-This call will return the rendered template:
-
-[source,js]
-------------------------------------------
-{
-  "template_output": {
-    "query": {
-      "terms": {
-        "status": [ <1>
-          "pending",
-          "published"
-        ]
-      }
-    }
-  }
-}
-------------------------------------------
-// TESTRESPONSE
-<1> `status` array has been populated with values from the `params` object.
-
-Pre-registered templates can also be rendered using
-
-[source,js]
-------------------------------------------
-GET _render/template/<template_name>
-{
-  "params": {
-    "..."
-  }
-}
-------------------------------------------
-// NOTCONSOLE
-
-[float]
-===== Explain
-
-You can use `explain` parameter when running a template:
-
-[source,js]
-------------------------------------------
-GET _search/template
-{
-  "id": "my_template",
-  "params": {
-    "status": [ "pending", "published" ]
-  },
-  "explain": true
-}
-------------------------------------------
-// CONSOLE
-// TEST[catch:missing]
-
-[float]
-===== Profiling
-
-You can use `profile` parameter when running a template:
-
-[source,js]
-------------------------------------------
-GET _search/template
-{
-  "id": "my_template",
-  "params": {
-    "status": [ "pending", "published" ]
-  },
-  "profile": true
-}
-------------------------------------------
-// CONSOLE
-// TEST[catch:missing]
-
 [[multi-search-template]]
 === Multi Search Template