Reorganise scripting docs (#18132)

* Reorganize scripting documentation

* Further changes to tidy up scripting docs

Closes #18116

* Add note about .lat/lon potentially returning null

* Added .value to expressions example

* Fixed two bad ASCIIDOC links

docs/reference/modules/scripting/security.asciidoc

@@ -1,5 +1,139 @@
 [[modules-scripting-security]]
-=== Scripting and the Java Security Manager
+=== Scripting and security
+
+You should never run Elasticsearch as the `root` user, as this would allow a
+script to access or do *anything* on your server, without limitations.
+
+You should not expose Elasticsearch directly to users, but instead have a
+proxy application inbetween. If you *do* intend to expose Elasticsearch
+directly to your users, then you have to decide whether you trust them enough
+to run scripts on your box or not, and apply the appropriate safety measures.
+
+[[enable-dynamic-scripting]]
+[float]
+=== Enabling dynamic scripting
+
+The `script.*` settings allow for <<security-script-fine,fine-grained>>
+control of which script languages (e.g `groovy`, `painless`) are allowed to
+run in which context ( e.g. `search`, `aggs`, `update`), and where the script
+source is allowed to come from (i.e. `inline`, `stored`, `file`).
+
+For instance, the following setting enables `stored` `update` scripts for
+`groovy`:
+
+[source,yaml]
+----------------
+script.engine.groovy.inline.update: true
+----------------
+
+Less fine-grained settings exist which allow you to enable or disable scripts
+for all sources, all languages, or all contexts.  The following settings
+enable `inline` and `stored` scripts for all languages in all contexts:
+
+[source,yaml]
+-----------------------------------
+script.inline: true
+script.stored: true
+-----------------------------------
+
+WARNING:  The above settings mean that anybody who can send requests to your
+Elasticsearch instance can run whatever scripts they choose! This is a
+security risk and may well lead to your Elasticsearch cluster being
+compromised.
+
+[[security-script-source]]
+[float]
+=== Script source settings
+
+Scripts may be enabled or disabled depending on their source: `inline`,
+`stored` in the cluster state, or from a `file` on each node in the cluster.
+Each of these settings takes one of these values:
+
+
+[horizontal]
+`false`::   Scripting is enabled.
+`true`::    Scripting is disabled.
+`sandbox`:: Scripting is enabled only for sandboxed languages.
+
+The default values are the following:
+
+[source,yaml]
+-----------------------------------
+script.inline: sandbox
+script.stored: sandbox
+script.file:   true
+-----------------------------------
+
+NOTE: Global scripting settings affect the `mustache` scripting language.
+<<search-template,Search templates>> internally use the `mustache` language,
+and will still be enabled by default as the `mustache` engine is sandboxed,
+but they will be enabled/disabled according to fine-grained settings
+specified in `elasticsearch.yml`.
+
+[[security-script-context]]
+[float]
+=== Script context settings
+
+Scripting may also be enabled or disabled in different contexts in the
+Elasticsearch API. The supported contexts are:
+
+[horizontal]
+`aggs`::    Aggregations
+`search`::  Search api, Percolator API and Suggester API
+`update`::  Update api
+`plugin`::  Any plugin that makes use of scripts under the generic `plugin` category
+
+Plugins can also define custom operations that they use scripts for instead
+of using the generic `plugin` category. Those operations can be referred to
+in the following form: `${pluginName}_${operation}`.
+
+The following example disables scripting for `update` and `plugin` operations,
+regardless of the script source or language. Scripts can still be executed
+from sandboxed languages as part of `aggregations`, `search` and plugins
+execution though, as the above defaults still get applied.
+
+[source,yaml]
+-----------------------------------
+script.update: false
+script.plugin: false
+-----------------------------------
+
+[[security-script-fine]]
+[float]
+=== Fine-grained script settings
+
+First, the high-level script settings described above are applied in order
+(context settings have precedence over source settings).  Then,  fine-grained
+settings which include the script language take precedence over any high-level
+settings.
+
+Fine-grained settings have the form:
+
+[source,yaml]
+------------------------
+script.engine.{lang}.{source}.{context}: true|false
+------------------------
+
+For example:
+
+[source,yaml]
+-----------------------------------
+script.inline: false <1>
+script.stored: false <1>
+script.file:   false <1>
+
+script.engine.groovy.stored.search:   true <2>
+script.engine.groovy.stored.aggs:     true <2>
+
+script.engine.mustache.stored.search: true <3>
+-----------------------------------
+<1> Disable all scripting from any source.
+<2> Allow stored Groovy scripts to be used for search and aggregations.
+<3> Allow stored Mustache templates to be used for search.
+
+[[java-security-manager]]
+[float]
+=== Java Security Manager
 
 Elasticsearch runs with the https://docs.oracle.com/javase/tutorial/essential/environment/security.html[Java Security Manager]
 enabled by default.  The security policy in Elasticsearch locks down the