[DOCS] Clarify geoshape orientation docs (#75888)

Adds additional information about how Elasticsearch uses polygon orientation. Elasticsearch only uses a polygon's orientation to determine if it crosses the international dateline. If so, Elasticsearch splits the polygon at the dateline.

Closes #74891

docs/reference/mapping/types/geo-shape.asciidoc

@@ -25,7 +25,8 @@ type.
 |Option |Description| Default
 
 |`orientation`
-a|Optional. Vertex order for the shape's coordinates list.
+a|Optional. Default <<polygon-orientation,orientation>> for the field's
+polygons.
 
 This parameter sets and returns only a `RIGHT` (counterclockwise) or `LEFT`
 (clockwise) value. However, you can specify either value in multiple ways.
@@ -43,12 +44,6 @@ variant:
 * `left`
 * `clockwise`
 * `cw`
-
-Defaults to `RIGHT` to comply with https://www.ogc.org/docs/is[OGC standards].
-OGC standards define outer ring vertices in counterclockwise order with inner
-ring (hole) vertices in clockwise order.
-
-Individual GeoJSON or WKT documents can override this parameter.
 | `RIGHT`
 
 |`ignore_malformed` |If true, malformed GeoJSON or WKT shapes are ignored. If
@@ -257,57 +252,45 @@ POST /example/_doc
 }
 --------------------------------------------------
 
-*IMPORTANT NOTE:* WKT does not enforce a specific order for vertices thus
-ambiguous polygons around the dateline and poles are possible.
-https://tools.ietf.org/html/rfc7946#section-3.1.6[GeoJSON] mandates that the
-outer polygon must be counterclockwise and interior shapes must be clockwise,
-which agrees with the Open Geospatial Consortium (OGC)
-https://www.opengeospatial.org/standards/sfa[Simple Feature Access]
-specification for vertex ordering.
+[discrete]
+[[polygon-orientation]]
+===== Polygon orientation
 
-Elasticsearch accepts both clockwise and counterclockwise polygons if they
-appear not to cross the dateline (i.e. they cross less than 180° of longitude),
-but for polygons that do cross the dateline (or for other polygons wider than
-180°) Elasticsearch requires the vertex ordering to comply with the OGC and
-GeoJSON specifications. Otherwise, an unintended polygon may be created and
-unexpected query/filter results will be returned.
+A polygon's orientation indicates the order of its vertices: `RIGHT`
+(counterclockwise) or `LEFT` (clockwise).
 
-The following provides an example of an ambiguous polygon. Elasticsearch will
-apply the GeoJSON standard to eliminate ambiguity resulting in a polygon that
-crosses the dateline.
+You can set a default orientation for a `geo_shape` field using the
+<<geo-shape-mapping-options,`orientation` mapping parameter>>. You can override
+this default for specific polygons using the document-level `orientation`
+parameter.
 
-[source,console]
---------------------------------------------------
-POST /example/_doc
-{
-  "location" : {
-    "type" : "polygon",
-    "coordinates" : [
-      [ [-177.0, 10.0], [176.0, 15.0], [172.0, 0.0], [176.0, -15.0], [-177.0, -10.0], [-177.0, 10.0] ],
-      [ [178.2, 8.2], [-178.8, 8.2], [-180.8, -8.8], [178.2, 8.8] ]
-    ]
-  }
-}
---------------------------------------------------
-// TEST[catch:/mapper_parsing_exception/]
-
-An `orientation` parameter can be defined when setting the `geo_shape` mapping (see <<geo-shape-mapping-options>>). This will define vertex
-order for the coordinate list on the mapped `geo_shape` field. It can also be overridden on each document. The following is an example for
-overriding the orientation on a document:
+For example, the following indexing request specifies a document-level
+`orientation` of `LEFT`.
 
 [source,console]
---------------------------------------------------
+----
 POST /example/_doc
 {
   "location" : {
     "type" : "polygon",
-    "orientation" : "clockwise",
+    "orientation" : "LEFT",
     "coordinates" : [
-      [ [100.0, 0.0], [100.0, 1.0], [101.0, 1.0], [101.0, 0.0], [100.0, 0.0] ]
+      [ [-177.0, 10.0], [176.0, 15.0], [172.0, 0.0], [176.0, -15.0], [-177.0, -10.0], [-177.0, 10.0] ]
     ]
   }
 }
---------------------------------------------------
+----
+
+{es} only uses a polygon’s orientation to determine if it crosses the
+international dateline (+/-180° longitude). If the difference between a
+polygon’s minimum longitude and the maximum longitude is less than 180°, the
+polygon doesn't cross the dateline and its orientation has no effect.
+
+If the difference between a polygon’s minimum longitude and the maximum
+longitude is 180° or greater, {es} checks whether the polygon's document-level
+`orientation` differs from the default in the `orientation` mapping parameter.
+If the orientation differs, {es} considers the polygon to cross the
+international dateline and splits the polygon at the dateline.
 
 [discrete]
 [[geo-multipoint]]

docs/reference/query-dsl/geo-shape-query.asciidoc

@@ -287,3 +287,6 @@ PUT /test/_doc/1
     }
 }
 --------------------------------------------------
+
+* The `geo_shape` query assumes `geo_shape` fields use a default `orientation`
+of `RIGHT` (counterclockwise). See <<polygon-orientation>>.