[Docs] user-defined subprograms... (yugabyte#13244)

* user-defined subprograms commit #1: changed '/the-sql-language/statements/' & added '/user-defined-subprograms-and-anon-blocks/'.

* further adjustments

* oops forgot the type on the new files

* add one more right nav

Co-authored-by: Alex Ball <aball@yugabyte.com>

docs/content/preview/api/ysql/_index.md

@@ -61,3 +61,22 @@ This section lists the main elements that support the YugabyteDB SQL language su
 - Names and Qualifiers: Some names are reserved for the system. List of [reserved names](reserved_names).
 - Data types: Most PostgreSQL-compatible data types are supported. List of [data types](datatypes/).
 - [Built-in SQL functions](exprs/)
+
+## Make sure that you have your own sandbox YugabyteDB cluster
+
+It always helps to have access to a sandbox YugabyteDB cluster where you can, when you need to, do whatever you want without considering any risk of doing harm. Here are the kinds of things you'll want to do:
+
+- Connect as the _postgres_ role and create and drop other _superusers_, and regular roles.
+- Create and drop databases
+- Create and drop extensions
+- Create and drop objects of all other kinds
+
+With these freedoms, you'll be able to set up any regime that you need to help you illustrate, or test, a hypothesis about how things work.
+
+Moreover, for some experiments, you'll need operating system access so that you can make changes to various configuration files (like the one that determines the default values for session parameters).
+
+It also helps to have a vanilla PostgreSQL installation on the same server so that you can confirm for yourself that the SQL systems of each (at least for the functionality that application developers use, and in the overwhelming majority of cases) are syntactically and semantically identical.
+
+To do all this confidently, you need to be sure that nobody else can use your sandbox so that you know that everything that you observe will be explained by what you deliberately did. Occasionally, you'll even want to destroy a cluster at one version and replace it with a cluster at a different version 
+
+The simplest way to achieve this ideal sandbox regime is to use you own laptop. The [Quick Start](../../quick-start/explore/ysql/) section shows you how to do this.

docs/content/preview/api/ysql/datatypes/_index.md

@@ -9,7 +9,7 @@ menu:
   preview:
     identifier: api-ysql-datatypes
     parent: api-ysql
-    weight: 4200
+    weight: 400
 aliases:
   - /preview/api/ysql/datatypes/
 type: indexpage

docs/content/preview/api/ysql/datatypes/type_datetime/typecasting-between-date-time-and-text.md

@@ -18,7 +18,7 @@ This section and its peer, [Timezones and _UTC offsets_](../timezones/), are pla
 Typecasting between _date-time_ values and _text_ values, rather than using explicit built-in functions like _to_char()_, _to_timestamp()_, or _to_date()_ allows the demonstration code to be uncluttered and easy to understand. However, as this section shows, the typecast semantics is sensitive to the current settings of the _DateStyle_ and _IntervalStyle_ session parameters.
 
 {{< note title="'Date-time' functions and operators in the PostgreSQL documentation." >}}
-PostgreSQL, and therefore YSQL, provide many functions and equivalent syntactical constructs that operate on, or produce, _date-time_ values. These are documented in these dedicated sections within the main section [Functions and operators](../../../exprs/) and its children:
+PostgreSQL, and therefore YSQL, provide many functions and equivalent syntactical constructs that operate on, or produce, _date-time_ values. These are documented in these dedicated sections within the main section [Built-in functions and operators](../../../exprs/) and its children:
 
 - [Date and time operators](../operators/).
 - [General-purpose date and time functions](../functions/).
@@ -117,10 +117,10 @@ And because _to_char_demo()_ uses the _at time zone_ operator, it is not sensiti
 ```output
  Friday / September
  Fri 07-Sep-1042 11:59:59.543216 BC
-
+ 
  Venerdì / Settembre
  Ven 07-Set-1042 11:59:59.543216 BC
-
+ 
  Perjantai / Syyskuu
  Pe 07-Syy-1042 11:59:59.543216 BC
 ```
@@ -380,22 +380,22 @@ Yugabyte recommends that application code should convert between _text_ values a
   drop table if exists t cascade;
   create table t(k int primary key, t1 time not null, t2 time not null);
   insert into t(k, t1, t2) values(1, '00:00:00'::time, '00:00:00'::time);
-
+  
   deallocate all;
   prepare s_1(text) as
   update t set t1 = to_timestamp($1, 'hh24:mi:ss')::time
   where k = 1;
-
+  
   prepare s_2(text) as
   update t set t2 = to_timestamp($1, 'hh24:mi:ss')::time
   where k = 1;
-
+  
   set timezone = 'UTC';
   execute s_1('13:00:56');
-
+  
   set timezone = 'America/Los_Angeles';
   execute s_2('13:00:56');
-
+  
   select (t1 = t2)::text from t where k = 1;
 ```
 
@@ -493,4 +493,4 @@ The _extract_ SQL functionality lets you assign values like the _years_ or _days
 Of course, it's safe to use the typecasting approach in _ad hoc_ tests where you can set _IntervalStyle_ to whatever you want to without worrying that it might affect the behavior of existing application code that doesn't set the parameter explicitly. The same applies to small stand-alone code examples that support documentation.
 
 The YSQL documentation assumes that _IntervalStyle_ is set to _'postgres'_ unless it's explicitly set otherwise.
-{{< /tip >}}
+{{< /tip >}}

docs/content/preview/api/ysql/datatypes/type_json/functions-operators/jsonb-object-agg.md

@@ -20,7 +20,8 @@ input value:       anyelement
 return value:      jsonb
 ```
 
-**Notes:** The syntax _"order by... nulls first"_ within the parentheses of the aggregate function (a generic feature of aggregate functions) isn't useful here because the order of the _key-value_ pairs of a JSON _object_ has no semantic significance. (The `::text` typecast of a `jsonb` _object_ uses the convention of ordering the pairs alphabetically by the key_.
+**Notes:** The syntax _"order by... nulls first"_ within the parentheses of the aggregate function (a generic feature of aggregate functions) isn't useful here because the order of the _key-value_ pairs of a JSON _object_ has no semantic significance. (The `::text` typecast of a `jsonb` _object_ uses the convention of ordering the pairs alphabetically by the _key_.
+
 ```plpgsql
 do $body$
 declare

docs/content/preview/api/ysql/datatypes/type_json/functions-operators/jsonb-populate-record.md

@@ -24,7 +24,7 @@ return value:      anyelement
 
 Use this `ysqlsh` script to create the required types _"t1"_ and _"t2"_, and then to execute the `ASSERT`.
 
-```
+```plpgsql
 create type t1 as ( d int, e text);
 create type t2 as (a int, b text[], c t1);
 

docs/content/preview/api/ysql/exprs/_index.md

@@ -1,14 +1,14 @@
 ---
-title: Functions and operators [YSQL]
-headerTitle: Functions and operators
-linkTitle: Functions and operators
+title: Built-in functions and operators [YSQL]
+headerTitle: Built-in functions and operators
+linkTitle: Built-in functions and operators
 description: YSQL supports all PostgreSQL-compatible built-in functions and operators.
 image: /images/section_icons/api/ysql.png
 menu:
   preview:
     identifier: api-ysql-exprs
     parent: api-ysql
-    weight: 4300
+    weight: 200
 aliases:
   - /preview/api/ysql/exprs/
 type: indexpage
@@ -18,11 +18,14 @@ YSQL supports all PostgreSQL-compatible built-in functions and operators. The fo
 
 | Statement | Description |
 |-----------|-------------|
-| [`currval`](func_currval) | Returns the last value returned by `nextval()` for the specified sequence in the current session |
-| [`lastval`](func_lastval) | Returns the value returned from the last call to `nextval()` (for any sequence) in the current session|
-| [`nextval`](func_nextval) | Returns the next value from the session's sequence cache |
-| [`yb_hash_code`](func_yb_hash_code) | Returns the partition hash code for a given set of expressions |
-| [`JSON functions and operators`](../datatypes/type_json/functions-operators/) | Detailed list of JSON-specific functions and operators |
-| [`Array functions and operators`](../datatypes/type_array/functions-operators/) | Detailed list of array-specific functions and operators |
-| [`Aggregate functions`](./aggregate_functions/) | Detailed list of YSQL aggregate functions |
-| [`Window functions`](./window_functions/) | Detailed list of YSQL window functions |
+| [nextval()](func_nextval) | Returns the next value for the specified sequence in the current session |
+| [currval()](func_currval) | Returns the value returned by the most recent call to _nextval()_ for the specified sequence in the current session |
+| [lastval()](func_lastval) | Returns the value returned by the most recent call to _nextval()_ for _any_ sequence in the current session |
+| [yb_hash_code()](func_yb_hash_code) | Returns the partition hash code for a given set of expressions |
+| [JSON functions and operators](../datatypes/type_json/functions-operators/) | Detailed list of JSON-specific functions and operators |
+| [Array functions and operators](../datatypes/type_array/functions-operators/) | Detailed list of array-specific functions and operators |
+| [Aggregate functions](./aggregate_functions/) | Detailed list of YSQL aggregate functions |
+| [Window functions](./window_functions/) | Detailed list of YSQL window functions |
+| [Date-time operators](../datatypes/type_datetime/operators/) | List of operators for the date and time data types |
+| [General-purpose date-functions](../datatypes/type_datetime/functions/) | List of general purpose functions for the date and time data types |
+| [Date-time formatting functions](../datatypes/type_datetime/formatting-functions/) | List of formatting functions for the date and time data types |

docs/content/preview/api/ysql/keywords.md

@@ -9,7 +9,7 @@ menu:
   preview:
     identifier: api-ysql-keywords
     parent: api-ysql
-    weight: 4500
+    weight: 500
 aliases:
   - /preview/api/ysql/keywords
 type: docs

docs/content/preview/api/ysql/reserved_names.md

@@ -9,7 +9,7 @@ menu:
   preview:
     identifier: api-ysql-reserved-names
     parent: api-ysql
-    weight: 4600
+    weight: 600
 aliases:
   - /preview/api/ysql/reserved_names
 type: docs

docs/content/preview/api/ysql/syntax_resources/call_procedure,fn_invocation,subprogram_arg.diagram.md

@@ -0,0 +1,12 @@
+#### call_procedure
+
+<svg class="rrdiagram" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" width="501" height="80" viewbox="0 0 501 80"><path class="connector" d="M0 52h15m50 0h10m133 0h10m25 0h50m-5 0q-5 0-5-5v-20q0-5 5-5h52m24 0h52q5 0 5 5v20q0 5-5 5m-5 0h40m-193 0q5 0 5 5v8q0 5 5 5h168q5 0 5-5v-8q0-5 5-5m5 0h10m25 0h15"/><polygon points="0,59 5,52 0,45" style="fill:black;stroke-width:0"/><rect class="literal" x="15" y="35" width="50" height="25" rx="7"/><text class="text" x="25" y="52">CALL</text><a xlink:href="../syntax_resources/grammar_diagrams#subprogram-name"><rect class="rule" x="75" y="35" width="133" height="25"/><text class="text" x="85" y="52">subprogram_name</text></a><rect class="literal" x="218" y="35" width="25" height="25" rx="7"/><text class="text" x="228" y="52">(</text><rect class="literal" x="340" y="5" width="24" height="25" rx="7"/><text class="text" x="350" y="22">,</text><a xlink:href="#subprogram-arg"><rect class="rule" x="293" y="35" width="118" height="25"/><text class="text" x="303" y="52">subprogram_arg</text></a><rect class="literal" x="461" y="35" width="25" height="25" rx="7"/><text class="text" x="471" y="52">)</text><polygon points="497,59 501,59 501,45 497,45" style="fill:black;stroke-width:0"/></svg>
+
+#### fn_invocation
+
+<svg class="rrdiagram" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" width="441" height="80" viewbox="0 0 441 80"><path class="connector" d="M0 52h15m133 0h10m25 0h50m-5 0q-5 0-5-5v-20q0-5 5-5h52m24 0h52q5 0 5 5v20q0 5-5 5m-5 0h40m-193 0q5 0 5 5v8q0 5 5 5h168q5 0 5-5v-8q0-5 5-5m5 0h10m25 0h15"/><polygon points="0,59 5,52 0,45" style="fill:black;stroke-width:0"/><a xlink:href="../syntax_resources/grammar_diagrams#subprogram-name"><rect class="rule" x="15" y="35" width="133" height="25"/><text class="text" x="25" y="52">subprogram_name</text></a><rect class="literal" x="158" y="35" width="25" height="25" rx="7"/><text class="text" x="168" y="52">(</text><rect class="literal" x="280" y="5" width="24" height="25" rx="7"/><text class="text" x="290" y="22">,</text><a xlink:href="#subprogram-arg"><rect class="rule" x="233" y="35" width="118" height="25"/><text class="text" x="243" y="52">subprogram_arg</text></a><rect class="literal" x="401" y="35" width="25" height="25" rx="7"/><text class="text" x="411" y="52">)</text><polygon points="437,59 441,59 441,45 437,45" style="fill:black;stroke-width:0"/></svg>
+
+#### subprogram_arg
+
+<svg class="rrdiagram" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" width="294" height="50" viewbox="0 0 294 50"><path class="connector" d="M0 22h35m81 0h10m40 0h20m-166 0q5 0 5 5v8q0 5 5 5h141q5 0 5-5v-8q0-5 5-5m5 0h10m83 0h15"/><polygon points="0,29 5,22 0,15" style="fill:black;stroke-width:0"/><a xlink:href="../syntax_resources/grammar_diagrams#arg-name"><rect class="rule" x="35" y="5" width="81" height="25"/><text class="text" x="45" y="22">arg_name</text></a><rect class="literal" x="126" y="5" width="40" height="25" rx="7"/><text class="text" x="136" y="22">=&gt;</text><a xlink:href="../syntax_resources/grammar_diagrams#expression"><rect class="rule" x="196" y="5" width="83" height="25"/><text class="text" x="206" y="22">expression</text></a><polygon points="290,29 294,29 294,15 290,15" style="fill:black;stroke-width:0"/></svg>
+

docs/content/preview/api/ysql/syntax_resources/call_procedure,fn_invocation,subprogram_arg.grammar.md

@@ -0,0 +1,8 @@
+```output.ebnf
+call_procedure ::= CALL subprogram_name ( [ subprogram_arg [ , ... ] ] 
+                   )
+
+fn_invocation ::= subprogram_name ( [ subprogram_arg [ , ... ] ] )
+
+subprogram_arg ::= [ arg_name => ] expression
+```

docs/content/preview/api/ysql/syntax_resources/exprs/aggregate_functions/group_by_clause,grouping_element.grammar.md

@@ -1,4 +1,4 @@
-```ebnf
+```output.ebnf
 group_by_clause ::= GROUP BY { grouping_element [ , ... ] }
 
 grouping_element ::= ( ) | ( expression [ , ... ] )

docs/content/preview/api/ysql/syntax_resources/exprs/aggregate_functions/having_clause.grammar.md

@@ -1,3 +1,3 @@
-```ebnf
+```output.ebnf
 having_clause ::= HAVING boolean_expression
 ```

docs/content/preview/api/ysql/syntax_resources/exprs/aggregate_functions/select_start,ordinary_aggregate_fn_invocation,within_group_aggregate_fn_invocation.grammar.md

@@ -1,4 +1,4 @@
-```ebnf
+```output.ebnf
 select_start ::= SELECT [ ALL | 
                           DISTINCT [ ON { ( expression [ , ... ] ) } ] ] 
                  [ * | { { expression

docs/content/preview/api/ysql/syntax_resources/exprs/window_functions/frame_clause,frame_bounds,frame_start,frame_end,frame_bound,frame_exclusion.grammar.md

@@ -1,4 +1,4 @@
-```ebnf
+```output.ebnf
 frame_clause ::= [ { RANGE | ROWS | GROUPS } frame_bounds ] 
                  [ frame_exclusion ]
 

docs/content/preview/api/ysql/syntax_resources/exprs/window_functions/select_start,window_clause,fn_over_window.grammar.md

@@ -1,4 +1,4 @@
-```ebnf
+```output.ebnf
 select_start ::= SELECT [ ALL | 
                           DISTINCT [ ON { ( expression [ , ... ] ) } ] ] 
                  [ * | { { expression

docs/content/preview/api/ysql/syntax_resources/exprs/window_functions/window_definition.grammar.md

@@ -1,4 +1,4 @@
-```ebnf
+```output.ebnf
 window_definition ::= ( [ name ]  
                       [ PARTITION BY order_expr [ , ... ] ]  
                       [ ORDER BY order_expr [ , ... ] ]