Document ESQL docs examples (#105197)

This adds some docs to the top of `docs.csv-spec` and
`docs-IT_tests_only.csv-spec` telling folks not to add more stuff there
and instead put new examples into whatever files they line up with. It
also shifts some things out of the file to "prime the pump" on cleaning
it up.

docs/reference/esql/processing-commands/drop.asciidoc

@@ -22,7 +22,7 @@ The `DROP` processing command removes one or more columns.
 
 [source,esql]
 ----
-include::{esql-specs}/docs.csv-spec[tag=dropheight]
+include::{esql-specs}/drop.csv-spec[tag=height]
 ----
 
 Rather than specify each column by name, you can use wildcards to drop all
@@ -30,5 +30,5 @@ columns with a name that matches a pattern:
 
 [source,esql]
 ----
-include::{esql-specs}/docs.csv-spec[tag=dropheightwithwildcard]
+include::{esql-specs}/drop.csv-spec[tag=heightWithWildcard]
 ----

docs/reference/esql/processing-commands/limit.asciidoc

@@ -43,5 +43,5 @@ settings:
 
 [source,esql]
 ----
-include::{esql-specs}/docs.csv-spec[tag=limit]
+include::{esql-specs}/limit.csv-spec[tag=basic]
 ----

x-pack/plugin/esql/qa/testFixtures/src/main/resources/docs-IT_tests_only.csv-spec

@@ -1,3 +1,16 @@
+// This file contains any ESQL snippets from the docs that don't have a home
+// anywhere else. The Isle of Misfit Toys. When you need to add new examples
+// for the docs you should try to convert an existing test first. Just add
+// the comments in whatever file the test already lives in. If you have to
+// write a new test to make an example in the docs then put it in whatever
+// file matches it's "theme" best. Put it next to similar tests. Not here.
+ 
+// Also! When Nik originally extracted examples from the docs to make them
+// testable he didn't spend a lot of time putting the docs into appropriate
+// files. He just made this one. He didn't put his toys away. We'd be better
+// off not adding to this strange toy-pile and instead moving things into
+// the appropriate files.
+
 enrich
 // tag::enrich[]
 ROW language_code = "1"  

x-pack/plugin/esql/qa/testFixtures/src/main/resources/docs.csv-spec

@@ -1,39 +1,15 @@
-docsDropHeight
-// tag::dropheight[]
-FROM employees 
-| DROP height
-// end::dropheight[]
-| LIMIT 0;
-
-avg_worked_seconds:long | birth_date:date | emp_no:integer | first_name:keyword | gender:keyword | height.float:double | height.half_float:double | height.scaled_float:double | hire_date:date | is_rehired:boolean | job_positions:keyword | languages:integer | languages.byte:integer | languages.long:long | languages.short:integer | last_name:keyword | salary:integer | salary_change:double | salary_change.int:integer |salary_change.keyword:keyword |salary_change.long:long | still_hired:boolean
-;
-
-docsDropHeightWithWildcard
-// tag::dropheightwithwildcard[]
-FROM employees 
-| DROP height*
-// end::dropheightwithwildcard[]
-| LIMIT 0;
-
-avg_worked_seconds:long | birth_date:date | emp_no:integer | first_name:keyword | gender:keyword | hire_date:date | is_rehired:boolean | job_positions:keyword | languages:integer | languages.byte:integer | languages.long:long | languages.short:integer | last_name:keyword | salary:integer | salary_change:double | salary_change.int:integer |salary_change.keyword:keyword |salary_change.long:long | still_hired:boolean
-;
-
-docsLimit
-// tag::limit[]
-FROM employees
-| SORT emp_no ASC
-| LIMIT 5
-// end::limit[]
-| KEEP emp_no
-;
-
-emp_no:integer
-10001
-10002
-10003
-10004
-10005
-;
+// This file contains any ESQL snippets from the docs that don't have a home
+// anywhere else. The Isle of Misfit Toys. When you need to add new examples
+// for the docs you should try to convert an existing test first. Just add
+// the comments in whatever file the test already lives in. If you have to
+// write a new test to make an example in the docs then put it in whatever
+// file matches its "theme" best. Put it next to similar tests. Not here.
+ 
+// Also! When Nik originally extracted examples from the docs to make them
+// testable he didn't spend a lot of time putting the docs into appropriate
+// files. He just made this one. He didn't put his toys away. We'd be better
+// off not adding to this strange toy-pile and instead moving things into
+// the appropriate files.
 
 docsKeep
 // tag::keep[]

x-pack/plugin/esql/qa/testFixtures/src/main/resources/drop.csv-spec

@@ -1,3 +1,23 @@
+height
+// tag::height[]
+FROM employees
+| DROP height
+// end::height[]
+| LIMIT 0;
+
+avg_worked_seconds:long | birth_date:date | emp_no:integer | first_name:keyword | gender:keyword | height.float:double | height.half_float:double | height.scaled_float:double | hire_date:date | is_rehired:boolean | job_positions:keyword | languages:integer | languages.byte:integer | languages.long:long | languages.short:integer | last_name:keyword | salary:integer | salary_change:double | salary_change.int:integer |salary_change.keyword:keyword |salary_change.long:long | still_hired:boolean
+;
+
+heightWithWildcard
+// tag::heightWithWildcard[]
+FROM employees 
+| DROP height*
+// end::heightWithWildcard[]
+| LIMIT 0;
+
+avg_worked_seconds:long | birth_date:date | emp_no:integer | first_name:keyword | gender:keyword | hire_date:date | is_rehired:boolean | job_positions:keyword | languages:integer | languages.byte:integer | languages.long:long | languages.short:integer | last_name:keyword | salary:integer | salary_change:double | salary_change.int:integer |salary_change.keyword:keyword |salary_change.long:long | still_hired:boolean
+;
+
 sortWithLimitOne_DropHeight
 from employees | sort languages, emp_no | limit 1 | drop height*;
 

x-pack/plugin/esql/qa/testFixtures/src/main/resources/limit.csv-spec

@@ -0,0 +1,16 @@
+basic
+// tag::basic[]
+FROM employees
+| SORT emp_no ASC
+| LIMIT 5
+// end::basic[]
+| KEEP emp_no
+;
+
+emp_no:integer
+10001
+10002
+10003
+10004
+10005
+;