SQL: document the use of a filter on _routing (#52355)

* Fix "Description"s for various sections in the functions pages.
* Added a TIP for searching using a routing key.
* Other small polishings

docs/reference/sql/endpoints/jdbc.asciidoc

@@ -208,7 +208,8 @@ connection. For example:
 include-tagged::{jdbc-tests}/SimpleExampleTestCase.java[simple_example]
 --------------------------------------------------
 
-NOTE:: {es-sql} doesn't provide a connection pooling mechanism, thus the connections
+[NOTE]
+{es-sql} doesn't provide a connection pooling mechanism, thus the connections
 the JDBC driver creates are not pooled. In order to achieve pooled connections,
 a third-party connection pooling mechanism is required. Configuring and setting up the
 third-party provider is outside the scope of this documentation.

docs/reference/sql/endpoints/rest.asciidoc

@@ -371,6 +371,26 @@ Douglas Adams  |The Hitchhiker's Guide to the Galaxy|180            |1979-10-12T
 // TESTRESPONSE[s/\|/\\|/ s/\+/\\+/]
 // TESTRESPONSE[non_json]
 
+[TIP]
+=================
+A useful and less obvious usage for standard query DSL filtering is to search documents by a specific <<search-routing, routing key>>.
+Because {es-sql} does not support a `routing` parameter, one can specify a <<mapping-routing-field, `terms` filter for the `_routing` field>> instead:
+
+[source,console]
+--------------------------------------------------
+POST /_sql?format=txt
+{
+    "query": "SELECT * FROM library",
+    "filter": {
+        "terms": {
+            "_routing": ["abc"]
+        }
+    }
+}
+--------------------------------------------------
+// TEST[setup:library]
+=================
+
 [[sql-rest-columnar]]
 === Columnar results
 

docs/reference/sql/functions/aggs.asciidoc

@@ -25,9 +25,7 @@ AVG(numeric_field) <1>
 
 *Output*: `double` numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Arithmetic_mean[Average] (arithmetic mean) of input values.
+*Description*: Returns the https://en.wikipedia.org/wiki/Arithmetic_mean[Average] (arithmetic mean) of input values.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -49,9 +47,7 @@ COUNT(expression) <1>
 
 *Output*: numeric value
 
-.Description:
-
-Returns the total number (count) of input values.
+*Description*: Returns the total number (count) of input values.
 
 In case of `COUNT(*)` or `COUNT(<literal>)`, _all_ values are considered (including `null` or missing ones).
 
@@ -79,9 +75,7 @@ COUNT(ALL field_name) <1>
 
 *Output*: numeric value
 
-.Description:
-
-Returns the total number (count) of all _non-null_ input values. `COUNT(<field_name>)` and `COUNT(ALL <field_name>)` are equivalent.
+*Description*: Returns the total number (count) of all _non-null_ input values. `COUNT(<field_name>)` and `COUNT(ALL <field_name>)` are equivalent.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -104,9 +98,7 @@ COUNT(DISTINCT field_name) <1>
 
 *Output*: numeric value
 
-.Description:
-
-Returns the total number of _distinct non-null_ values in input values.
+*Description*: Returns the total number of _distinct non-null_ values in input values.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -131,9 +123,7 @@ FIRST(
 
 *Output*: same type as the input
 
-.Description:
-
-Returns the first **non-NULL** value (if such exists) of the `field_name` input column sorted by
+*Description*: Returns the first **non-NULL** value (if such exists) of the `field_name` input column sorted by
 the `ordering_field_name` column. If `ordering_field_name` is not provided, only the `field_name`
 column is used for the sorting. E.g.:
 
@@ -228,10 +218,8 @@ LAST(
 
 *Output*: same type as the input
 
-.Description:
-
-It's the inverse of <<sql-functions-aggs-first>>. Returns the last **non-NULL** value (if such exists) of the
-`field_name`input column sorted descending by the `ordering_field_name` column. If `ordering_field_name` is not
+*Description*: It's the inverse of <<sql-functions-aggs-first>>. Returns the last **non-NULL** value (if such exists) of the
+`field_name` input column sorted descending by the `ordering_field_name` column. If `ordering_field_name` is not
 provided, only the `field_name` column is used for the sorting. E.g.:
 
 [cols="<,<"]
@@ -322,9 +310,7 @@ MAX(field_name) <1>
 
 *Output*: same type as the input
 
-.Description:
-
-Returns the maximum value across input values in the field `field_name`.
+*Description*: Returns the maximum value across input values in the field `field_name`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -350,9 +336,7 @@ MIN(field_name) <1>
 
 *Output*: same type as the input
 
-.Description:
-
-Returns the minimum value across input values in the field `field_name`.
+*Description*: Returns the minimum value across input values in the field `field_name`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -378,9 +362,7 @@ SUM(field_name) <1>
 
 *Output*: `bigint` for integer input, `double` for floating points
 
-.Description:
-
-Returns the sum of input values in the field `field_name`.
+*Description*: Returns the sum of input values in the field `field_name`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -406,7 +388,7 @@ KURTOSIS(field_name) <1>
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 https://en.wikipedia.org/wiki/Kurtosis[Quantify] the shape of the distribution of input values in the field `field_name`.
 
@@ -430,7 +412,7 @@ MAD(field_name) <1>
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 https://en.wikipedia.org/wiki/Median_absolute_deviation[Measure] the variability of the input values in the field `field_name`.
 
@@ -457,7 +439,7 @@ PERCENTILE(
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 Returns the nth https://en.wikipedia.org/wiki/Percentile[percentile] (represented by `numeric_exp` parameter)
 of input values in the field `field_name`.
@@ -485,7 +467,7 @@ PERCENTILE_RANK(
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 Returns the nth https://en.wikipedia.org/wiki/Percentile_rank[percentile rank] (represented by `numeric_exp` parameter)
 of input values in the field `field_name`.
@@ -510,7 +492,7 @@ SKEWNESS(field_name) <1>
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 https://en.wikipedia.org/wiki/Skewness[Quantify] the asymmetric distribution of input values in the field `field_name`.
 
@@ -534,7 +516,7 @@ STDDEV_POP(field_name) <1>
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 Returns the https://en.wikipedia.org/wiki/Standard_deviations[population standard deviation] of input values in the field `field_name`.
 
@@ -558,7 +540,7 @@ SUM_OF_SQUARES(field_name) <1>
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 Returns the https://en.wikipedia.org/wiki/Total_sum_of_squares[sum of squares] of input values in the field `field_name`.
 
@@ -582,7 +564,7 @@ VAR_POP(field_name) <1>
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 Returns the https://en.wikipedia.org/wiki/Variance[population variance] of input values in the field `field_name`.
 

docs/reference/sql/functions/conditional.asciidoc

@@ -26,9 +26,7 @@ an _ELSE *default_result_* clause. Every *condition* should be a boolean express
 the *default_result* if all _WHEN *condition_* clauses evaluate to `false`. If the optional _ELSE *default_result_*
 clause is missing and all _WHEN *condition_* clauses evaluate to `false` then `null` is returned.
 
-.Description
-
-The CASE expression is a generic conditional expression which simulates if/else statements of other programming languages
+*Description*: The CASE expression is a generic conditional expression which simulates if/else statements of other programming languages
 If the condition’s result is true, the value of the result expression that follows the condition will be the returned
 the subsequent when clauses will be skipped and not processed.
 
@@ -148,9 +146,7 @@ COALESCE can take an arbitrary number of arguments.
 
 *Output*: one of the expressions or `null`
 
-.Description
-
-Returns the first of its arguments that is not null.
+*Description*: Returns the first of its arguments that is not null.
 If all arguments are null, then it returns `null`.
 
 
@@ -192,9 +188,7 @@ all of them must be of the same data type.
 
 *Output*: one of the expressions or `null`
 
-.Description
-
-Returns the argument that has the largest value which is not null.
+*Description*: Returns the argument that has the largest value which is not null.
 If all arguments are null, then it returns `null`.
 
 
@@ -229,9 +223,7 @@ IFNULL(
 
 *Output*: 2nd expression if 1st expression is null, otherwise 1st expression.
 
-.Description
-
-Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
+*Description*: Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
 Returns the first of its arguments that is not null.
 If all arguments are null, then it returns `null`.
 
@@ -270,9 +262,7 @@ IIF(
 *Output*: 2nd expression if 1st expression (condition) evaluates to `true`. If it evaluates to `false`
 return 3rd expression. If 3rd expression is not provided return `null`.
 
-.Description
-
-Conditional function that implements the standard _IF <condition> THEN <result1> ELSE <result2>_
+*Description*: Conditional function that implements the standard _IF <condition> THEN <result1> ELSE <result2>_
 logic of programming languages. If the 3rd expression is not provided and the condition evaluates to `false`,
 `null` is returned.
 
@@ -317,9 +307,7 @@ ISNULL(
 
 *Output*: 2nd expression if 1st expression is null, otherwise 1st expression.
 
-.Description
-
-Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
+*Description*: Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
 Returns the first of its arguments that is not null.
 If all arguments are null, then it returns `null`.
 
@@ -363,9 +351,7 @@ all of them must be of the same data type.
 
 *Output*: one of the expressions or `null`
 
-.Description
-
-Returns the argument that has the smallest value which is not null.
+*Description*: Returns the argument that has the smallest value which is not null.
 If all arguments are null, then it returns `null`.
 
 
@@ -401,9 +387,7 @@ NULLIF(
 
 *Output*: `null` if the 2 expressions are equal, otherwise the 1st expression.
 
-.Description
-
-Returns `null` when the two input expressions are equal and
+*Description*: Returns `null` when the two input expressions are equal and
 if not, it returns the 1st expression.
 
 
@@ -438,9 +422,7 @@ NVL(
 
 *Output*: 2nd expression if 1st expression is null, otherwise 1st expression.
 
-.Description
-
-Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
+*Description*: Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
 Returns the first of its arguments that is not null.
 If all arguments are null, then it returns `null`.
 

docs/reference/sql/functions/date-time.asciidoc

@@ -106,9 +106,7 @@ CURDATE()
 
 *Output*: date
 
-.Description:
-
-Returns the date (no time part) when the current query reached the server.
+*Description*: Returns the date (no time part) when the current query reached the server.
 It can be used both as a keyword: `CURRENT_DATE` or as a function with no arguments: `CURRENT_DATE()`.
 
 [NOTE]
@@ -156,9 +154,7 @@ CURTIME
 
 *Output*: time
 
-.Description:
-
-Returns the time when the current query reached the server.
+*Description*: Returns the time when the current query reached the server.
 As a function, `CURRENT_TIME()` accepts _precision_ as an optional
 parameter for rounding the second fractional digits (nanoseconds). The default _precision_ is 3,
 meaning a milliseconds precision current time will be returned.
@@ -212,9 +208,7 @@ CURRENT_TIMESTAMP([precision]) <1>
 
 *Output*: date/time
 
-.Description:
-
-Returns the date/time when the current query reached the server.
+*Description*: Returns the date/time when the current query reached the server.
 As a function, `CURRENT_TIMESTAMP()` accepts _precision_ as an optional
 parameter for rounding the second fractional digits (nanoseconds). The default _precision_ is 3,
 meaning a milliseconds precision current date/time will be returned.
@@ -269,9 +263,7 @@ if a negative value is used it results to a subtraction from the date/datetime
 
 *Output*: datetime
 
-.Description:
-
-Add the given number of date/time units to a date/datetime. If the number of units is negative then it's subtracted from
+*Description*: Add the given number of date/time units to a date/datetime. If the number of units is negative then it's subtracted from
 the date/datetime. If any of the three arguments is `null` a `null` is returned.
 
 [WARNING]
@@ -346,9 +338,7 @@ DATE_DIFF(
 
 *Output*: integer
 
-.Description:
-
-Subtract the second argument from the third argument and return their difference in multiples of the unit
+*Description*: Subtract the second argument from the third argument and return their difference in multiples of the unit
 specified in the first argument. If the second argument (start) is greater than the third argument (end),
 then negative values are returned. If any of the three arguments is `null`, a `null` is returned.
 
@@ -432,9 +422,7 @@ DATE_PART(
 
 *Output*: integer
 
-.Description:
-
-Extract the specified unit from a date/datetime. If any of the two arguments is `null` a `null` is returned.
+*Description*: Extract the specified unit from a date/datetime. If any of the two arguments is `null` a `null` is returned.
 It's similar to <<sql-functions-datetime-extract>> but with different names and aliases for the units and
 provides more options (e.g.: `TZOFFSET`).
 
@@ -522,9 +510,7 @@ DATE_TRUNC(
 
 *Output*: datetime
 
-.Description:
-
-Truncate the date/datetime to the specified unit by setting all fields that are less significant than the specified
+*Description*: Truncate the date/datetime to the specified unit by setting all fields that are less significant than the specified
 one to zero (or one, for day, day of week and month). If any of the two arguments is `null` a `null` is returned.
 
 [cols="^,^"]
@@ -592,9 +578,7 @@ DAY_OF_MONTH(datetime_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Extract the day of the month from a date/datetime.
+*Description*: Extract the day of the month from a date/datetime.
 
 [source, sql]
 --------------------------------------------------
@@ -616,9 +600,7 @@ DAY_OF_WEEK(datetime_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Extract the day of the week from a date/datetime. Sunday is `1`, Monday is `2`, etc.
+*Description*: Extract the day of the week from a date/datetime. Sunday is `1`, Monday is `2`, etc.
 
 [source, sql]
 --------------------------------------------------
@@ -640,9 +622,7 @@ DAY_OF_YEAR(datetime_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Extract the day of the year from a date/datetime.
+*Description*: Extract the day of the year from a date/datetime.
 
 [source, sql]
 --------------------------------------------------
@@ -664,9 +644,7 @@ DAY_NAME(datetime_exp) <1>
 
 *Output*: string
 
-.Description:
-
-Extract the day of the week from a date/datetime in text format (`Monday`, `Tuesday`...).
+*Description*: Extract the day of the week from a date/datetime in text format (`Monday`, `Tuesday`...).
 
 [source, sql]
 --------------------------------------------------
@@ -688,9 +666,7 @@ HOUR_OF_DAY(datetime_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Extract the hour of the day from a date/datetime.
+*Description*: Extract the hour of the day from a date/datetime.
 
 [source, sql]
 --------------------------------------------------
@@ -712,9 +688,7 @@ ISO_DAY_OF_WEEK(datetime_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Extract the day of the week from a date/datetime, following the https://en.wikipedia.org/wiki/ISO_week_date[ISO 8601 standard].
+*Description*: Extract the day of the week from a date/datetime, following the https://en.wikipedia.org/wiki/ISO_week_date[ISO 8601 standard].
 Monday is `1`, Tuesday is `2`, etc.
 
 [source, sql]
@@ -737,9 +711,7 @@ ISO_WEEK_OF_YEAR(datetime_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Extract the week of the year from a date/datetime, following https://en.wikipedia.org/wiki/ISO_week_date[ISO 8601 standard]. The first week
+*Description*: Extract the week of the year from a date/datetime, following https://en.wikipedia.org/wiki/ISO_week_date[ISO 8601 standard]. The first week
 of a year is the first week with a majority (4 or more) of its days in January.
 
 [source, sql]
@@ -762,9 +734,7 @@ MINUTE_OF_DAY(datetime_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Extract the minute of the day from a date/datetime.
+*Description*: Extract the minute of the day from a date/datetime.
 
 [source, sql]
 --------------------------------------------------
@@ -786,9 +756,7 @@ MINUTE_OF_HOUR(datetime_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Extract the minute of the hour from a date/datetime.
+*Description*: Extract the minute of the hour from a date/datetime.
 
 [source, sql]
 --------------------------------------------------
@@ -810,9 +778,7 @@ MONTH(datetime_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Extract the month of the year from a date/datetime.
+*Description*: Extract the month of the year from a date/datetime.
 
 [source, sql]
 --------------------------------------------------
@@ -834,9 +800,7 @@ MONTH_NAME(datetime_exp) <1>
 
 *Output*: string
 
-.Description:
-
-Extract the month from a date/datetime in text format (`January`, `February`...).
+*Description*: Extract the month from a date/datetime in text format (`January`, `February`...).
 
 [source, sql]
 --------------------------------------------------
@@ -856,9 +820,7 @@ NOW()
 
 *Output*: datetime
 
-.Description:
-
-This function offers the same functionality as <<sql-functions-current-timestamp,CURRENT_TIMESTAMP()>> function: returns
+*Description*: This function offers the same functionality as <<sql-functions-current-timestamp,CURRENT_TIMESTAMP()>> function: returns
 the datetime when the current query reached the server. This method always returns the same value for its every
 occurrence within the same query.
 
@@ -890,9 +852,7 @@ SECOND_OF_MINUTE(datetime_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Extract the second of the minute from a date/datetime.
+*Description*: Extract the second of the minute from a date/datetime.
 
 [source, sql]
 --------------------------------------------------
@@ -914,9 +874,7 @@ QUARTER(datetime_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Extract the year quarter the date/datetime falls in.
+*Description*: Extract the year quarter the date/datetime falls in.
 
 [source, sql]
 --------------------------------------------------
@@ -936,9 +894,7 @@ TODAY()
 
 *Output*: date
 
-.Description:
-
-This function offers the same functionality as <<sql-functions-current-date,CURRENT_DATE()>> function: returns
+*Description*: This function offers the same functionality as <<sql-functions-current-date,CURRENT_DATE()>> function: returns
 the date when the current query reached the server. This method always returns the same value for its every occurrence
 within the same query.
 
@@ -970,9 +926,7 @@ WEEK_OF_YEAR(datetime_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Extract the week of the year from a date/datetime.
+*Description*: Extract the week of the year from a date/datetime.
 
 [source, sql]
 --------------------------------------------------
@@ -994,9 +948,7 @@ YEAR(datetime_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Extract the year from a date/datetime.
+*Description*: Extract the year from a date/datetime.
 
 [source, sql]
 --------------------------------------------------
@@ -1021,9 +973,7 @@ EXTRACT(
 
 *Output*: integer
 
-.Description:
-
-Extract fields from a date/datetime by specifying the name of a <<sql-functions-datetime,datetime function>>.
+*Description*: Extract fields from a date/datetime by specifying the name of a <<sql-functions-datetime,datetime function>>.
 The following
 
 [source, sql]

docs/reference/sql/functions/geo.asciidoc

@@ -39,9 +39,7 @@ ST_AsWKT(
 
 *Output*: string
 
-.Description:
-
-Returns the WKT representation of the `geometry`.
+*Description*: Returns the WKT representation of the `geometry`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -66,9 +64,7 @@ ST_WKTToSQL(
 
 *Output*: geometry
 
-.Description:
-
-Returns the geometry from WKT representation.
+*Description*: Returns the geometry from WKT representation.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -94,9 +90,7 @@ ST_GeometryType(
 
 *Output*: string
 
-.Description:
-
-Returns the type of the `geometry` such as POINT, MULTIPOINT, LINESTRING, MULTILINESTRING, POLYGON, MULTIPOLYGON, GEOMETRYCOLLECTION, ENVELOPE or CIRCLE.
+*Description*: Returns the type of the `geometry` such as POINT, MULTIPOINT, LINESTRING, MULTILINESTRING, POLYGON, MULTIPOLYGON, GEOMETRYCOLLECTION, ENVELOPE or CIRCLE.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -120,9 +114,7 @@ ST_X(
 
 *Output*: double
 
-.Description:
-
-Returns the longitude of the first point in the geometry.
+*Description*: Returns the longitude of the first point in the geometry.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -146,9 +138,7 @@ ST_Y(
 
 *Output*: double
 
-.Description:
-
-Returns the latitude of the first point in the geometry.
+*Description*: Returns the latitude of the first point in the geometry.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -172,9 +162,7 @@ ST_Z(
 
 *Output*: double
 
-.Description:
-
-Returns the altitude of the first point in the geometry.
+*Description*: Returns the altitude of the first point in the geometry.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -200,9 +188,7 @@ ST_Distance(
 
 *Output*: Double
 
-.Description:
-
-Returns the distance between geometries in meters. Both geometries have to be points.
+*Description*: Returns the distance between geometries in meters. Both geometries have to be points.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------

docs/reference/sql/functions/grouping.asciidoc

@@ -30,16 +30,15 @@ HISTOGRAM(
 
 *Output*: non-empty buckets or groups of the given expression divided according to the given interval
 
-.Description
-
-The histogram function takes all matching values and divides them into buckets with fixed size matching the given interval, using (roughly) the following formula:
+*Description*: The histogram function takes all matching values and divides them into buckets with fixed size matching the given interval, using (roughly) the following formula:
 
 [source, sql]
 ----
 bucket_key = Math.floor(value / interval) * interval
 ----
 
-NOTE:: The histogram in SQL does *NOT* return empty buckets for missing intervals as the traditional <<search-aggregations-bucket-histogram-aggregation, histogram>> and  <<search-aggregations-bucket-datehistogram-aggregation, date histogram>>. Such behavior does not fit conceptually in SQL which treats all missing values as `NULL`; as such the histogram places all missing values in the `NULL` group.
+[NOTE]
+The histogram in SQL does *NOT* return empty buckets for missing intervals as the traditional <<search-aggregations-bucket-histogram-aggregation, histogram>> and  <<search-aggregations-bucket-datehistogram-aggregation, date histogram>>. Such behavior does not fit conceptually in SQL which treats all missing values as `NULL`; as such the histogram places all missing values in the `NULL` group.
 
 `Histogram` can be applied on either numeric fields:
 

docs/reference/sql/functions/like-rlike.asciidoc

@@ -27,9 +27,7 @@ LIKE constant_exp <2>
 <1> typically a field, or a constant expression
 <2> pattern
 
-.Description:
-
-The SQL `LIKE` operator is used to compare a value to similar values using wildcard operators. There are two wildcards used in conjunction
+*Description*: The SQL `LIKE` operator is used to compare a value to similar values using wildcard operators. There are two wildcards used in conjunction
 with the `LIKE` operator:
 
 * The percent sign (%)
@@ -67,9 +65,7 @@ RLIKE constant_exp <2>
 <1> typically a field, or a constant expression
 <2> pattern
 
-.Description:
-
-This operator is similar to `LIKE`, but the user is not limited to search for a string based on a fixed pattern with the percent sign (`%`)
+*Description*: This operator is similar to `LIKE`, but the user is not limited to search for a string based on a fixed pattern with the percent sign (`%`)
 and underscore (`_`); the pattern in this case is a regular expression which allows the construction of more flexible patterns.
 
 For more details about the regular expressions syntax, https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html[Java's Pattern class javadoc]

docs/reference/sql/functions/math.asciidoc

@@ -25,9 +25,7 @@ ABS(numeric_exp) <1>
 
 *Output*: numeric
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Absolute_value[absolute value] of `numeric_exp`. The return type is the same as the input type.
+*Description*: Returns the https://en.wikipedia.org/wiki/Absolute_value[absolute value] of `numeric_exp`. The return type is the same as the input type.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -49,9 +47,7 @@ CBRT(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Cube_root[cube root] of `numeric_exp`.
+*Description*: Returns the https://en.wikipedia.org/wiki/Cube_root[cube root] of `numeric_exp`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -73,9 +69,7 @@ CEIL(numeric_exp) <1>
 
 *Output*: integer or long numeric value
 
-.Description:
-
-Returns the smallest integer greater than or equal to `numeric_exp`.
+*Description*: Returns the smallest integer greater than or equal to `numeric_exp`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -95,9 +89,7 @@ E()
 
 *Output*: `2.718281828459045`
 
-.Description:
-
-Returns https://en.wikipedia.org/wiki/E_%28mathematical_constant%29[Euler's number].
+*Description*: Returns https://en.wikipedia.org/wiki/E_%28mathematical_constant%29[Euler's number].
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -119,9 +111,7 @@ EXP(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns https://en.wikipedia.org/wiki/Exponential_function[Euler's number at the power] of `numeric_exp` e^numeric_exp^.
+*Description*: Returns https://en.wikipedia.org/wiki/Exponential_function[Euler's number at the power] of `numeric_exp` e^numeric_exp^.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -143,9 +133,7 @@ EXPM1(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#expm1-double-[Euler's number at the power] of `numeric_exp` minus 1 (e^numeric_exp^ - 1).
+*Description*: Returns https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#expm1-double-[Euler's number at the power] of `numeric_exp` minus 1 (e^numeric_exp^ - 1).
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -167,9 +155,7 @@ FLOOR(numeric_exp) <1>
 
 *Output*: integer or long numeric value
 
-.Description:
-
-Returns the largest integer less than or equal to `numeric_exp`.
+*Description*: Returns the largest integer less than or equal to `numeric_exp`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -191,9 +177,7 @@ LOG(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Natural_logarithm[natural logarithm] of `numeric_exp`.
+*Description*: Returns the https://en.wikipedia.org/wiki/Natural_logarithm[natural logarithm] of `numeric_exp`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -215,9 +199,7 @@ LOG10(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Common_logarithm[base 10 logarithm] of `numeric_exp`.
+*Description*: Returns the https://en.wikipedia.org/wiki/Common_logarithm[base 10 logarithm] of `numeric_exp`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -237,9 +219,7 @@ PI()
 
 *Output*: `3.141592653589793`
 
-.Description:
-
-Returns https://en.wikipedia.org/wiki/Pi[PI number].
+*Description*: Returns https://en.wikipedia.org/wiki/Pi[PI number].
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -264,9 +244,7 @@ POWER(
 
 *Output*: double numeric value
 
-.Description:
-
-Returns the value of `numeric_exp` to the power of `integer_exp`.
+*Description*: Returns the value of `numeric_exp` to the power of `integer_exp`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -293,9 +271,7 @@ RANDOM(seed) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns a random double using the given seed.
+*Description*: Returns a random double using the given seed.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -319,8 +295,7 @@ ROUND(
 
 *Output*: numeric 
 
-.Description:
-Returns `numeric_exp` rounded to `integer_exp` places right of the decimal point. If `integer_exp` is negative,
+*Description*: Returns `numeric_exp` rounded to `integer_exp` places right of the decimal point. If `integer_exp` is negative,
 `numeric_exp` is rounded to |`integer_exp`| places to the left of the decimal point. If `integer_exp` is omitted,
 the function will perform as if `integer_exp` would be 0. The returned numeric data type is the same as the data type 
 of `numeric_exp`.
@@ -350,9 +325,7 @@ SIGN(numeric_exp) <1>
 
 *Output*: [-1, 0, 1]
 
-.Description:
-
-Returns an indicator of the sign of `numeric_exp`. If `numeric_exp` is less than zero, –1 is returned. If `numeric_exp` equals zero, 0 is returned. If `numeric_exp` is greater than zero, 1 is returned.
+*Description*: Returns an indicator of the sign of `numeric_exp`. If `numeric_exp` is less than zero, –1 is returned. If `numeric_exp` equals zero, 0 is returned. If `numeric_exp` is greater than zero, 1 is returned.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -375,9 +348,7 @@ SQRT(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns https://en.wikipedia.org/wiki/Square_root[square root] of `numeric_exp`.
+*Description*: Returns https://en.wikipedia.org/wiki/Square_root[square root] of `numeric_exp`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -401,8 +372,7 @@ TRUNCATE(
 
 *Output*: numeric 
 
-.Description:
-Returns `numeric_exp` truncated to `integer_exp` places right of the decimal point. If `integer_exp` is negative,
+*Description*: Returns `numeric_exp` truncated to `integer_exp` places right of the decimal point. If `integer_exp` is negative,
 `numeric_exp` is truncated to |`integer_exp`| places to the left of the decimal point.  If `integer_exp` is omitted,
 the function will perform as if `integer_exp` would be 0. The returned numeric data type is the same as the data type 
 of `numeric_exp`.
@@ -436,9 +406,7 @@ ACOS(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arccosine] of `numeric_exp` as an angle, expressed in radians.
+*Description*: Returns the https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arccosine] of `numeric_exp` as an angle, expressed in radians.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -460,9 +428,7 @@ ASIN(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arcsine] of `numeric_exp` as an angle, expressed in radians.
+*Description*: Returns the https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arcsine] of `numeric_exp` as an angle, expressed in radians.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -484,9 +450,7 @@ ATAN(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arctangent] of `numeric_exp` as an angle, expressed in radians.
+*Description*: Returns the https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arctangent] of `numeric_exp` as an angle, expressed in radians.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -511,9 +475,7 @@ ATAN2(
 
 *Output*: double numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Atan2[arctangent of the `ordinate` and `abscisa` coordinates] specified as an angle, expressed in radians.
+*Description*: Returns the https://en.wikipedia.org/wiki/Atan2[arctangent of the `ordinate` and `abscisa` coordinates] specified as an angle, expressed in radians.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -535,9 +497,7 @@ COS(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#cosine[cosine] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians.
+*Description*: Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#cosine[cosine] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -559,9 +519,7 @@ COSH(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Hyperbolic_function[hyperbolic cosine] of `numeric_exp`.
+*Description*: Returns the https://en.wikipedia.org/wiki/Hyperbolic_function[hyperbolic cosine] of `numeric_exp`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -583,9 +541,7 @@ COT(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#Cosecant,_secant,_and_cotangent[cotangent] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians.
+*Description*: Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#Cosecant,_secant,_and_cotangent[cotangent] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -607,9 +563,7 @@ DEGREES(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Convert from https://en.wikipedia.org/wiki/Radian[radians]
+*Description*: Convert from https://en.wikipedia.org/wiki/Radian[radians]
 to https://en.wikipedia.org/wiki/Degree_(angle)[degrees].
 
 ["source","sql",subs="attributes,macros"]
@@ -632,9 +586,7 @@ RADIANS(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Convert from https://en.wikipedia.org/wiki/Degree_(angle)[degrees]
+*Description*: Convert from https://en.wikipedia.org/wiki/Degree_(angle)[degrees]
 to https://en.wikipedia.org/wiki/Radian[radians].
 
 ["source","sql",subs="attributes,macros"]
@@ -657,9 +609,7 @@ SIN(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#sine[sine] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians.
+*Description*: Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#sine[sine] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -681,9 +631,7 @@ SINH(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Hyperbolic_function[hyperbolic sine] of `numeric_exp`.
+*Description*: Returns the https://en.wikipedia.org/wiki/Hyperbolic_function[hyperbolic sine] of `numeric_exp`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -705,9 +653,7 @@ TAN(numeric_exp) <1>
 
 *Output*: double numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#tangent[tangent] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians.
+*Description*: Returns the https://en.wikipedia.org/wiki/Trigonometric_functions#tangent[tangent] of `numeric_exp`, where `numeric_exp` is an angle expressed in radians.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------

docs/reference/sql/functions/search.asciidoc

@@ -26,9 +26,7 @@ MATCH(
 <2> matching text
 <3> additional parameters; optional
 
-.Description:
-
-A full-text search option, in the form of a predicate, available in {es-sql} that gives the user control over powerful <<query-dsl-match-query,match>>
+*Description*: A full-text search option, in the form of a predicate, available in {es-sql} that gives the user control over powerful <<query-dsl-match-query,match>>
 and <<query-dsl-multi-match-query,multi_match>> {es} queries.
 
 The first parameter is the field or fields to match against. In case it receives one value only, {es-sql} will use a `match` query to perform the search:
@@ -83,9 +81,7 @@ QUERY(
 <1> query text
 <2> additional parameters; optional
 
-.Description:
-
-Just like `MATCH`, `QUERY` is a full-text search predicate that gives the user control over the <<query-dsl-query-string-query,query_string>> query in {es}.
+*Description*: Just like `MATCH`, `QUERY` is a full-text search predicate that gives the user control over the <<query-dsl-query-string-query,query_string>> query in {es}.
 
 The first parameter is basically the input that will be passed as is to the `query_string` query, which means that anything that `query_string`
 accepts in its `query` field can be used here as well:
@@ -133,9 +129,7 @@ SCORE()
 
 *Output*: `double` numeric value
 
-.Description:
-
-Returns the {defguide}/relevance-intro.html[relevance] of a given input to the executed query. 
+*Description*: Returns the {defguide}/relevance-intro.html[relevance] of a given input to the executed query. 
 The higher score, the more relevant the data.
 
 NOTE: When doing multiple text queries in the `WHERE` clause then, their scores will be

docs/reference/sql/functions/string.asciidoc

@@ -20,9 +20,7 @@ ASCII(string_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Returns the ASCII code value of the leftmost character of `string_exp` as an integer.
+*Description*: Returns the ASCII code value of the leftmost character of `string_exp` as an integer.
 
 [source, sql]
 --------------------------------------------------
@@ -43,9 +41,7 @@ BIT_LENGTH(string_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Returns the length in bits of the `string_exp` input expression.
+*Description*: Returns the length in bits of the `string_exp` input expression.
 
 [source, sql]
 --------------------------------------------------
@@ -66,9 +62,7 @@ CHAR(code) <1>
 
 *Output*: string
 
-.Description:
-
-Returns the character that has the ASCII code value specified by the numeric input. The value should be between 0 and 255; otherwise, the return value is data source–dependent.
+*Description*: Returns the character that has the ASCII code value specified by the numeric input. The value should be between 0 and 255; otherwise, the return value is data source–dependent.
 
 [source, sql]
 --------------------------------------------------
@@ -89,9 +83,7 @@ CHAR_LENGTH(string_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Returns the length in characters of the input, if the string expression is of a character data type; otherwise, returns the length in bytes of the string expression (the smallest integer not less than the number of bits divided by 8).
+*Description*: Returns the length in characters of the input, if the string expression is of a character data type; otherwise, returns the length in bytes of the string expression (the smallest integer not less than the number of bits divided by 8).
 
 [source, sql]
 --------------------------------------------------
@@ -115,9 +107,7 @@ CONCAT(
 
 *Output*: string
 
-.Description:
-
-Returns a character string that is the result of concatenating `string_exp1` to `string_exp2`. If one of the string is `NULL`, the other string will be returned.
+*Description*: Returns a character string that is the result of concatenating `string_exp1` to `string_exp2`. If one of the string is `NULL`, the other string will be returned.
 
 [source, sql]
 --------------------------------------------------
@@ -145,9 +135,7 @@ INSERT(
 
 *Output*: string
 
-.Description:
-
-Returns a string where `length` characters have been deleted from `source`, beginning at `start`, and where `replacement` has been inserted into `source`, beginning at `start`.
+*Description*: Returns a string where `length` characters have been deleted from `source`, beginning at `start`, and where `replacement` has been inserted into `source`, beginning at `start`.
 
 [source, sql]
 --------------------------------------------------
@@ -168,9 +156,7 @@ LCASE(string_exp) <1>
 
 *Output*: string
 
-.Description:
-
-Returns a string equal to that in `string_exp`, with all uppercase characters converted to lowercase.
+*Description*: Returns a string equal to that in `string_exp`, with all uppercase characters converted to lowercase.
 
 [source, sql]
 --------------------------------------------------
@@ -194,9 +180,7 @@ LEFT(
 
 *Output*: string
 
-.Description:
-
-Returns the leftmost count characters of `string_exp`.
+*Description*: Returns the leftmost count characters of `string_exp`.
 
 [source, sql]
 --------------------------------------------------
@@ -217,9 +201,7 @@ LENGTH(string_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Returns the number of characters in `string_exp`, excluding trailing blanks.
+*Description*: Returns the number of characters in `string_exp`, excluding trailing blanks.
 
 [source, sql]
 --------------------------------------------------
@@ -246,9 +228,7 @@ LOCATE(
 
 *Output*: integer
 
-.Description:
-
-Returns the starting position of the first occurrence of `pattern` within `source`. The search for the first occurrence of `pattern` begins with the first character position in `source` unless the optional argument, `start`, is specified. If `start` is specified, the search begins with the character position indicated by the value of `start`. The first character position in `source` is indicated by the value 1. If `pattern` is not found within `source`, the value 0 is returned.
+*Description*: Returns the starting position of the first occurrence of `pattern` within `source`. The search for the first occurrence of `pattern` begins with the first character position in `source` unless the optional argument, `start`, is specified. If `start` is specified, the search begins with the character position indicated by the value of `start`. The first character position in `source` is indicated by the value 1. If `pattern` is not found within `source`, the value 0 is returned.
 
 [source, sql]
 --------------------------------------------------
@@ -274,9 +254,7 @@ LTRIM(string_exp) <1>
 
 *Output*: string
 
-.Description:
-
-Returns the characters of `string_exp`, with leading blanks removed.
+*Description*: Returns the characters of `string_exp`, with leading blanks removed.
 
 [source, sql]
 --------------------------------------------------
@@ -297,9 +275,7 @@ OCTET_LENGTH(string_exp) <1>
 
 *Output*: integer
 
-.Description:
-
-Returns the length in bytes of the `string_exp` input expression.
+*Description*: Returns the length in bytes of the `string_exp` input expression.
 
 [source, sql]
 --------------------------------------------------
@@ -323,9 +299,7 @@ POSITION(
 
 *Output*: integer
 
-.Description:
-
-Returns the position of the `string_exp1` in `string_exp2`. The result is an exact numeric.
+*Description*: Returns the position of the `string_exp1` in `string_exp2`. The result is an exact numeric.
 
 [source, sql]
 --------------------------------------------------
@@ -349,9 +323,7 @@ REPEAT(
 
 *Output*: string
 
-.Description:
-
-Returns a character string composed of `string_exp` repeated `count` times.
+*Description*: Returns a character string composed of `string_exp` repeated `count` times.
 
 [source, sql]
 --------------------------------------------------
@@ -377,9 +349,7 @@ REPLACE(
 
 *Output*: string
 
-.Description:
-
-Search `source` for occurrences of `pattern`, and replace with `replacement`.
+*Description*: Search `source` for occurrences of `pattern`, and replace with `replacement`.
 
 [source, sql]
 --------------------------------------------------
@@ -403,9 +373,7 @@ RIGHT(
 
 *Output*: string
 
-.Description:
-
-Returns the rightmost count characters of `string_exp`.
+*Description*: Returns the rightmost count characters of `string_exp`.
 
 [source, sql]
 --------------------------------------------------
@@ -426,9 +394,7 @@ RTRIM(string_exp) <1>
 
 *Output*: string
 
-.Description:
-
-Returns the characters of `string_exp` with trailing blanks removed.
+*Description*: Returns the characters of `string_exp` with trailing blanks removed.
 
 [source, sql]
 --------------------------------------------------
@@ -449,9 +415,7 @@ SPACE(count) <1>
 
 *Output*: string
 
-.Description:
-
-Returns a character string consisting of `count` spaces.
+*Description*: Returns a character string consisting of `count` spaces.
 
 [source, sql]
 --------------------------------------------------
@@ -477,9 +441,7 @@ SUBSTRING(
 
 *Output*: string
 
-.Description:
-
-Returns a character string that is derived from `source`, beginning at the character position specified by `start` for `length` characters.
+*Description*: Returns a character string that is derived from `source`, beginning at the character position specified by `start` for `length` characters.
 
 [source, sql]
 --------------------------------------------------
@@ -500,9 +462,7 @@ UCASE(string_exp) <1>
 
 *Output*: string
 
-.Description:
-
-Returns a string equal to that of the input, with all lowercase characters converted to uppercase.
+*Description*: Returns a string equal to that of the input, with all lowercase characters converted to uppercase.
 
 [source, sql]
 --------------------------------------------------

docs/reference/sql/functions/system.asciidoc

@@ -18,9 +18,7 @@ DATABASE()
 
 *Output*: string
 
-.Description:
-
-Returns the name of the database being queried. In the case of Elasticsearch SQL, this
+*Description*: Returns the name of the database being queried. In the case of Elasticsearch SQL, this
 is the name of the Elasticsearch cluster. This function should always return a non-null
 value.
 
@@ -41,9 +39,7 @@ USER()
 
 *Output*: string
 
-.Description:
-
-Returns the username of the authenticated user executing the query. This function can
+*Description*: Returns the username of the authenticated user executing the query. This function can
 return `null` in case <<elasticsearch-security,security>> is disabled.
 
 [source, sql]

docs/reference/sql/functions/type-conversion.asciidoc

@@ -19,9 +19,7 @@ CAST(
 <1> Expression to cast
 <2> Target data type to cast to
 
-.Description
-
-Casts the result of the given expression to the target <<sql-data-types, data type>>.
+*Description*: Casts the result of the given expression to the target <<sql-data-types, data type>>.
 If the cast is not possible (for example because of target type is too narrow or because
 the value itself cannot be converted), the query fails.
 
@@ -60,9 +58,7 @@ CONVERT(
 <1> Expression to convert
 <2> Target data type to convert to
 
-.Description
-
-Works exactly like <<sql-functions-type-conversion-cast>> with slightly different syntax.
+*Description*: Works exactly like <<sql-functions-type-conversion-cast>> with slightly different syntax.
 Moreover, apart from the standard <<sql-data-types, data types>> it supports the corresponding
 https://docs.microsoft.com/en-us/sql/odbc/reference/appendixes/explicit-data-type-conversion-function?view=sql-server-2017[ODBC data types].
 

docs/reference/sql/language/syntax/commands/describe-table.asciidoc

@@ -3,7 +3,7 @@
 [[sql-syntax-describe-table]]
 === DESCRIBE TABLE
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
 DESCRIBE
@@ -26,9 +26,7 @@ DESC
 <1> single table identifier or double quoted es multi index
 <2> SQL LIKE pattern
 
-.Description
-
-`DESC` and `DESCRIBE` are aliases to <<sql-syntax-show-columns>>.
+*Description*: `DESC` and `DESCRIBE` are aliases to <<sql-syntax-show-columns>>.
 
 [source, sql]
 ----

docs/reference/sql/language/syntax/commands/select.asciidoc

@@ -3,7 +3,7 @@
 [[sql-syntax-select]]
 === SELECT
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
 SELECT select_expr [, ...]
@@ -16,9 +16,7 @@ SELECT select_expr [, ...]
 [ PIVOT ( aggregation_expr FOR column IN ( value [ [ AS ] alias ] [, ...] ) ) ]
 ----
 
-.Description
-
-Retrieves rows from zero or more tables.
+*Description*: Retrieves rows from zero or more tables.
 
 The general execution of `SELECT` is as follows:
 

docs/reference/sql/language/syntax/commands/show-columns.asciidoc

@@ -3,7 +3,7 @@
 [[sql-syntax-show-columns]]
 === SHOW COLUMNS
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
 SHOW COLUMNS [ FROM | IN ]?
@@ -17,9 +17,7 @@ SHOW COLUMNS [ FROM | IN ]?
 See <<sql-index-patterns, index patterns>> for more information about
 patterns.
 
-.Description
-
-List the columns in table and their data type (and other attributes).
+*Description*: List the columns in table and their data type (and other attributes).
 
 [source, sql]
 ----

docs/reference/sql/language/syntax/commands/show-functions.asciidoc

@@ -3,7 +3,7 @@
 [[sql-syntax-show-functions]]
 === SHOW FUNCTIONS
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
 SHOW FUNCTIONS [LIKE pattern?]? <1>
@@ -11,9 +11,7 @@ SHOW FUNCTIONS [LIKE pattern?]? <1>
 
 <1> SQL match pattern
 
-.Description
-
-List all the SQL functions and their type. The `LIKE` clause can be used to restrict the list of names to the given pattern.
+*Description*: List all the SQL functions and their type. The `LIKE` clause can be used to restrict the list of names to the given pattern.
 
 [source, sql]
 ----

docs/reference/sql/language/syntax/commands/show-tables.asciidoc

@@ -3,7 +3,7 @@
 [[sql-syntax-show-tables]]
 === SHOW TABLES
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
 SHOW TABLES
@@ -20,9 +20,7 @@ See <<sql-index-patterns, index patterns>> for more information about
 patterns.
 
 
-.Description
-
-List the tables available to the current user and their type.
+*Description*: List the tables available to the current user and their type.
 
 [source, sql]
 ----

docs/reference/sql/language/syntax/lexic/index.asciidoc

@@ -121,7 +121,8 @@ SELECT "first_name" <1>
 <1> Double quotes `"` used for column and table identifiers
 <2> Single quotes `'` used for a string literal
 
-NOTE:: to escape single or double quotes, one needs to use that specific quote one more time. For example, the literal `John's` can be escaped like
+[NOTE]
+To escape single or double quotes, one needs to use that specific quote one more time. For example, the literal `John's` can be escaped like
 `SELECT 'John''s' AS name`. The same goes for double quotes escaping - `SELECT 123 AS "test""number"` will display as a result a column with the name `test"number`.
 
 [[sql-syntax-special-chars]]