Large scale overhaul, copy editing and fixes

(sorry, not an atomic commit...)

Author: mrotteveel

src/docs/asciidoc/en/refdocs/fblangref25/_fblangref25-dml.adoc

@@ -1279,8 +1279,7 @@ This means that it successfully matches every row in the left source to every ro
 <cross-join> ::= {CROSS JOIN | ,} <source>
 ----
 
-Please notice that the comma syntax is deprecated!
-It is only supported to keep legacy code working and may disappear in some future version.
+Use of the comma syntax is discouraged, and we recommend using the explicit join syntax.
 
 Cross-joining two sets is equivalent to joining them on a tautology (a condition that is always true).
 The following two statements have the same effect:

src/docs/asciidoc/en/refdocs/fblangref25/_fblangref25-dochist.adoc

@@ -11,10 +11,12 @@ The exact file history is recorded in our _git_ repository; see https://github.c
 4+|Revision History
 
 |1.13
-|TBD 2023
+|26 May 2023
 |MR
 a|* Added missing context variable names for <<fblangref25-functions-scalarfuncs-get-context>>
-* ...
+* Replaced mention that implicit join is deprecated and might get removed;
+its use is merely discouraged.
+* Removed incorrect `ROLE` keyword from example in <<fblangref25-security-rdbadmin01>>
 
 |1.12
 |10 May 2023

src/docs/asciidoc/en/refdocs/fblangref25/_fblangref25-security.adoc

@@ -197,9 +197,9 @@ In a regular database, the `RDB$ADMIN` role is granted and revoked with the usua
 
 [listing,subs=+quotes]
 ----
-GRANT [ROLE] RDB$ADMIN TO _username_
+GRANT RDB$ADMIN TO _username_
 
-REVOKE [ROLE] RDB$ADMIN FROM _username_
+REVOKE RDB$ADMIN FROM _username_
 ----
 
 In order to grant and revoke the `RDB$ADMIN` role, the grantor must be logged in as an <<fblangref25-security-administrators,administrator>>.

src/docs/asciidoc/en/refdocs/fblangref25/firebird-25-language-reference.adoc

@@ -1,7 +1,7 @@
 [[fblangref25]]
 = Firebird 2.5 Language Reference
 Dmitry Filippov; Alexander Karpeykin; Alexey Kovyazin; Dmitry Kuzmenko; Denis Simonov; Paul Vinkenoog; Dmitry Yemanov
-1.13, TBD 2023
+1.13, 26 May 2023
 :doctype: book
 :sectnums:
 :sectanchors:

src/docs/asciidoc/en/refdocs/fblangref30/_fblangref30-dml.adoc

@@ -1403,8 +1403,7 @@ This means that it successfully matches every row in the left source to every ro
 <cross-join> ::= {CROSS JOIN | ,} <source>
 ----
 
-Please notice that the comma syntax is deprecated!
-It is only supported to keep legacy code working and may disappear in some future version.
+Use of the comma syntax is discouraged, and we recommend using the explicit join syntax.
 
 Cross-joining two sets is equivalent to joining them on a tautology (a condition that is always true).
 The following two statements have the same effect:
@@ -1456,12 +1455,6 @@ FROM customers c, sales s
 WHERE s.cust_id = c.id AND c.city = 'Detroit'
 ----
 
-[IMPORTANT]
-====
-The implicit join syntax is deprecated and may be removed in a future version.
-We recommend using the explicit join syntax shown earlier.
-====
-
 [[fblangref30-dml-select-joins-mix-implexpl]]
 ===== Mixing Explicit and Implicit Joins
 
@@ -1538,39 +1531,6 @@ But please notice again that, especially in outer joins, plain `colname` isn't a
 Types may differ, and one of the qualified columns may be `NULL` while the other isn't.
 In that case, the value in the merged, unqualified column may mask the fact that one of the source values is absent.
 
-[[fblangref30-dml-select-joins-storedprocs]]
-==== Joins with stored procedures
-
-If a join is performed with a stored procedure that is not correlated with other data streams via input parameters, there are no oddities.
-If correlation _is_ involved, an unpleasant quirk reveals itself.
-The problem is that the optimizer denies itself any way to determine the interrelationships of the input parameters of the procedure from the fields in the other streams:
-
-[source]
-----
-SELECT *
-FROM MY_TAB
-JOIN MY_PROC(MY_TAB.F) ON 1 = 1;
-----
-
-Here, the procedure will be executed before a single record has been retrieved from the table, `MY_TAB`.
-The `isc_no_cur_rec error` error (_no current record for fetch operation_) is raised, interrupting the execution.
-
-The solution is to use syntax that specifies the join order _explicitly_:
-
-[source]
-----
-SELECT *
-FROM MY_TAB
-LEFT JOIN MY_PROC(MY_TAB.F) ON 1 = 1;
-----
-
-This forces the table to be read before the procedure and everything works correctly.
-
-[TIP]
-====
-This quirk has been recognised as a bug in the optimizer and will be fixed in the next version of Firebird.
-====
-
 [[fblangref30-dml-select-where]]
 === The `WHERE` clause
 
@@ -4065,12 +4025,8 @@ Notice that the old values (1 and 2) are used to update the b column even after
 
 [NOTE]
 ====
-It was not always like that.
-Before version 2.5, columns got their new values immediately upon assignment.
-It was non-standard behaviour that was fixed in version 2.5.
-
-To maintain compatibility with legacy code, the configuration file `firebird.conf` includes the parameter `OldSetClauseSemantics`, that can be set True (1) to restore the old, bad behaviour.
-It is a temporary measure -- the parameter will be removed in the future.
+Before Firebird 2.5, columns got their new values immediately upon assignment.
+It was non-standard behaviour that was fixed in Firebird 2.5.
 ====
 
 [[fblangref30-dml-update-whereclause]]

src/docs/asciidoc/en/refdocs/fblangref30/_fblangref30-dochist.adoc

@@ -11,11 +11,14 @@ The exact file history is recorded in our _git_ repository; see https://github.c
 4+|Revision History
 
 |1.15
-|TBD 2023
+|26 May 2023
 |MR
 a|* Added missing context variable names for <<fblangref30-scalarfuncs-get-context>>
 * `CURRENT_CONNECTION` returns `BIGINT`
-* ...
+* Removed section _Joins with stored procedures_ as it no longer applies
+* Replaced mention that implicit join is deprecated and might get removed;
+its use is merely discouraged.
+* Removed incorrect `ROLE` keyword from example in <<fblangref30-security-rdbadmin01>>
 
 |1.14
 |10 May 2023

src/docs/asciidoc/en/refdocs/fblangref30/_fblangref30-psql.adoc

@@ -1677,7 +1677,7 @@ END
 |A logical condition returning TRUE, FALSE or UNKNOWN
 |===
 
-The `CONTINUE` statement skips the remainer of the current block of a loop and starts the next iteration of the current `WHILE` or `FOR` loop.
+The `CONTINUE` statement skips the remainder of the current block of a loop and starts the next iteration of the current `WHILE` or `FOR` loop.
 Using the optional _label_ parameter, `CONTINUE` can also start the next iteration of an outer loop, that is, the loop labelled with _label_.
 
 [[fblangref30-psql-continue-exmpl]]

src/docs/asciidoc/en/refdocs/fblangref30/firebird-30-language-reference.adoc

@@ -1,7 +1,7 @@
 [[fblangref30]]
 = Firebird 3.0 Language Reference
 Dmitry Filippov; Alexander Karpeykin; Alexey Kovyazin; Dmitry Kuzmenko; Denis Simonov; Paul Vinkenoog; Dmitry Yemanov; Mark Rotteveel
-1.15, TBD 2023
+1.15, 26 May 2023
 :doctype: book
 :sectnums:
 :sectanchors:

src/docs/asciidoc/en/refdocs/fblangref30/security/_fblangref30-security-auth.adoc

@@ -216,9 +216,9 @@ In a regular database, the `RDB$ADMIN` role is granted and revoked with the usua
 
 [listing,subs=+quotes]
 ----
-GRANT [ROLE] RDB$ADMIN TO _username_
+GRANT RDB$ADMIN TO _username_
 
-REVOKE [ROLE] RDB$ADMIN FROM _username_
+REVOKE RDB$ADMIN FROM _username_
 ----
 
 [[fblangref30-security-tbl-rdbadmin0]]

src/docs/asciidoc/en/refdocs/fblangref40/_fblangref40-datatypes.adoc

@@ -675,8 +675,7 @@ The actual precision of values stored in or read from time(stamp) functions and
 * `CURRENT_TIMESTAMP` and `LOCALTIMESTAMP` default to milliseconds precision.
 Precision from seconds to milliseconds can be specified with `CURRENT_TIMESTAMP (0|1|2|3)` or `LOCALTIMESTAMP (0|1|2|3)`
 * Literal `'NOW'` defaults to milliseconds precision
-* Function `DATEADD()` supports up to deci-milliseconds precision with `MILLISECOND`
-* Function `DATEDIFF()` only supports up to milliseconds precision
+* Functions `DATEADD()` and -- since Firebird 4.0.1 -- `DATEDIFF()` support up to deci-milliseconds precision with `MILLISECOND`
 * The `EXTRACT()` function returns up to deci-milliseconds precision with the `SECOND` and `MILLISECOND` arguments
 * the '```{plus}```' and '```-```' operators work with deci-milliseconds precision.
 
@@ -695,7 +694,7 @@ Storing at UTC has some caveats:
 - When you use named zones, and the time zone rules for that zone change, the UTC time stays the same, but the local time in the named zone may change.
 - For `TIME WITH TIME ZONE`, calculating a time zone offset for a named zone to get the local time in the zone applies the rules valid at the 1st of January 2020 to ensure a stable value.
 This may result in unexpected or confusing results.
-- When the rules of a named time zone changes, a value in the affected date range may longer match the intended value if the actual offset in that named zone changes.
+- When the rules of a named time zone changes, a value in the affected date range may no longer match the intended value if the actual offset in that named zone changes.
 ****
 
 [[fblangref40-datatypes-date]]
@@ -2428,7 +2427,7 @@ For more information, see <<fblangref40-datatypes-array>>
 <array_datatype> ::=
     {SMALLINT | INT[EGER] | BIGINT | INT128} <array_dim>
   | {REAL | FLOAT [(_bin_prec_)] | DOUBLE PRECISION} <array_dim>
-  | DECFLOAT [(_dec_prec_)]
+  | DECFLOAT [(_dec_prec_)] <array_dim>
   | BOOLEAN <array_dim>
   | DATE <array_dim>
   | TIME [{WITHOUT | WITH} TIME ZONE] <array_dim>

src/docs/asciidoc/en/refdocs/fblangref40/_fblangref40-dml.adoc

@@ -1422,8 +1422,7 @@ This means that it successfully matches every row in the left source to every ro
 <cross-join> ::= {CROSS JOIN | ,} <source>
 ----
 
-Please notice that the comma syntax is deprecated!
-It is only supported to keep legacy code working and may disappear in some future version.
+Use of the comma syntax is discouraged, and we recommend using the explicit join syntax.
 
 Cross-joining two sets is equivalent to joining them on a tautology (a condition that is always true).
 The following two statements have the same effect:
@@ -1475,12 +1474,6 @@ FROM customers c, sales s
 WHERE s.cust_id = c.id AND c.city = 'Detroit'
 ----
 
-[IMPORTANT]
-====
-The implicit join syntax is deprecated and may be removed in a future version.
-We recommend using the explicit join syntax shown earlier.
-====
-
 [[fblangref40-dml-select-joins-mix-implexpl]]
 ===== Mixing Explicit and Implicit Joins
 
@@ -1557,39 +1550,6 @@ But please notice again that, especially in outer joins, plain `colname` isn't a
 Types may differ, and one of the qualified columns may be `NULL` while the other isn't.
 In that case, the value in the merged, unqualified column may mask the fact that one of the source values is absent.
 
-[[fblangref40-dml-select-joins-storedprocs]]
-==== Joins with stored procedures
-
-If a join is performed with a stored procedure that is not correlated with other data streams via input parameters, there are no oddities.
-If correlation _is_ involved, an unpleasant quirk reveals itself.
-The problem is that the optimizer denies itself any way to determine the interrelationships of the input parameters of the procedure from the fields in the other streams:
-
-[source]
-----
-SELECT *
-FROM MY_TAB
-JOIN MY_PROC(MY_TAB.F) ON 1 = 1;
-----
-
-Here, the procedure will be executed before a single record has been retrieved from the table, `MY_TAB`.
-The `isc_no_cur_rec error` error (_no current record for fetch operation_) is raised, interrupting the execution.
-
-The solution is to use syntax that specifies the join order _explicitly_:
-
-[source]
-----
-SELECT *
-FROM MY_TAB
-LEFT JOIN MY_PROC(MY_TAB.F) ON 1 = 1;
-----
-
-This forces the table to be read before the procedure and everything works correctly.
-
-[TIP]
-====
-This quirk has been recognised as a bug in the optimizer and will be fixed in the next version of Firebird.
-====
-
 [[fblangref40-dml-select-joins-lateral]]
 ==== Joins with `LATERAL` Derived Tables
 
@@ -4266,16 +4226,6 @@ A B
 
 Notice that the old values (1 and 2) are used to update the b column even after the column was assigned a new value (5). 
 
-[NOTE]
-====
-It was not always like that.
-Before version 2.5, columns got their new values immediately upon assignment.
-It was non-standard behaviour that was fixed in version 2.5.
-
-To maintain compatibility with legacy code, the configuration file `firebird.conf` includes the parameter `OldSetClauseSemantics`, that can be set True (1) to restore the old, bad behaviour.
-It is a temporary measure -- the parameter will be removed in the future.
-====
-
 [[fblangref40-dml-update-whereclause]]
 === The `WHERE` Clause
 

src/docs/asciidoc/en/refdocs/fblangref40/_fblangref40-dochist.adoc

@@ -11,13 +11,18 @@ The exact file history is recorded in our _git_ repository; see https://github.c
 4+|Revision History
 
 |2.5
-|TBD 2023
+|26 May 2023
 |MR
 a|* Added missing context variable names for <<fblangref40-scalarfuncs-get-context>>
 * Documented hex-literal support for `INT128` since 4.0.1
 * `CURRENT_CONNECTION` returns `BIGINT`
 * Example for `RDB$ROLE_IN_USE()` should use `RDB$ROLES` (https://github.com/FirebirdSQL/firebird-documentation/issues/184[#184])
-* ...
+* Removed section _Joins with stored procedures_ as it no longer applies
+* Replaced mention that implicit join is deprecated and might get removed;
+its use is merely discouraged.
+* Added note in <<fblangref40-scalarfuncs-tbl-encrypt-req>> about AES variants
+* Replaced incorrect `ROLE` keyword with `DEFAULT` in example in <<fblangref40-security-rdbadmin01>>
+* Miscellaneous copy-editing
 
 |2.4
 |10 May 2023

src/docs/asciidoc/en/refdocs/fblangref40/_fblangref40-functions-scalar.adoc

@@ -4620,7 +4620,10 @@ We recommend searching the internet for further details on the algorithms.
 |AES
 |16, 24, 32
 |16
-|{nbsp}
+a|Key size determines the AES variant: +
+16 bytes -> AES-128 +
+24 bytes -> AES-192 +
+32 bytes -> AES-256
 
 |ANUBIS
 |16 - 40, in steps of 4

src/docs/asciidoc/en/refdocs/fblangref40/_fblangref40-psql.adoc

@@ -1793,7 +1793,7 @@ END
 |A logical condition returning TRUE, FALSE or UNKNOWN
 |===
 
-The `CONTINUE` statement skips the remainer of the current block of a loop and starts the next iteration of the current `WHILE` or `FOR` loop.
+The `CONTINUE` statement skips the remainder of the current block of a loop and starts the next iteration of the current `WHILE` or `FOR` loop.
 Using the optional _label_ parameter, `CONTINUE` can also start the next iteration of an outer loop, that is, the loop labelled with _label_.
 
 [[fblangref40-psql-continue-exmpl]]

src/docs/asciidoc/en/refdocs/fblangref40/firebird-40-language-reference.adoc

@@ -1,7 +1,7 @@
 [[fblangref40]]
 = Firebird 4.0 Language Reference
 Dmitry Filippov; Alexander Karpeykin; Alexey Kovyazin; Dmitry Kuzmenko; Denis Simonov; Paul Vinkenoog; Dmitry Yemanov; Mark Rotteveel
-2.5, TBD 2023
+2.5, 26 May 2023
 :doctype: book
 :sectnums:
 :sectanchors:

src/docs/asciidoc/en/refdocs/fblangref40/security/_fblangref40-security-auth.adoc

@@ -235,11 +235,11 @@ Depending on the administrative status of the current user, more parameters may
 [[fblangref40-security-rdbadmin05]]
 ==== Using the `RDB$ADMIN` Role in the Security Database
 
-To manage user accounts through SQL, the grantee must specify the `RDB$ADMIN` role when connecting or through `SET ROLE`.
-No user can connect to the security database remotely, so the solution is that the user connects to a regular database where they also have `RDB$ADMIN` rights, supplying the `RDB$ADMIN` role in their login parameters.
+To manage user accounts through SQL, the user must have the `RDB$ADMIN` role in the security database.
+No user can connect to the security database remotely, so the solution is that the user connects to a regular database.
 From there, they can submit any SQL user management command.
 
-If there is no regular database where the user has the `RDB$ADMIN` role, then account management via SQL queries is not possible, unless they connect directly to the security database using an embedded connection.
+Contrary to Firebird 3.0 or earlier, the user does not need to specify the `RDB$ADMIN` role on connect, nor do they need to have the `RDB$ADMIN` role in the database used to connect.
 
 [[fblangref40-security-rdbadmin0]]
 ===== Using _gsec_ with `RDB$ADMIN Rights`
@@ -253,9 +253,9 @@ In a regular database, the `RDB$ADMIN` role is granted and revoked with the usua
 
 [listing,subs=+quotes]
 ----
-GRANT [ROLE] RDB$ADMIN TO _username_
+GRANT [DEFAULT] RDB$ADMIN TO _username_
 
-REVOKE [ROLE] RDB$ADMIN FROM _username_
+REVOKE [DEFAULT] RDB$ADMIN FROM _username_
 ----
 
 [[fblangref40-security-tbl-rdbadmin0]]

src/docs/asciidoc/en/refdocs/fblangref40/security/_fblangref40-security-sql-security.adoc

@@ -4,13 +4,13 @@
 The `SQL SECURITY` clause of various DDL statements enables executable objects (triggers, stored procedures, stored functions) to be defined to run in a specific context of privileges.
 
 The SQL Security feature has two contexts: `INVOKER` and `DEFINER`.
-The `INVOKER` context corresponds to the privileges available to the current user or the calling object, while `DEFINERE` corresponds to those available to the owner of the object.
+The `INVOKER` context corresponds to the privileges available to the current user or the calling object, while `DEFINER` corresponds to those available to the owner of the object.
 
 The `SQL SECURITY` property is an optional part of an object's definition that can be applied to the object with DDL statements.
 The property cannot be dropped, but it can be changed from `INVOKER` to `DEFINER` and vice versa.
 
 This is not the same thing as SQL privileges, which are applied to users and some types of database objects to give them various types of access to other database objects.
-When an executable object is Firebird needs access to a table, view or another executable object, the target object is not accessible if the invoker does not have the necessary privileges on that object.
+When an executable object in Firebird needs access to a table, view or another executable object, the target object is not accessible if the invoker does not have the necessary privileges on that object.
 That has been the situation in previous Firebird versions and remains so in Firebird 4.0.
 That is, by default all executable objects have the `SQL SECURITY INVOKER` property, and any caller lacking the necessary privileges will be rejected.
 The default SQL Security behaviour of a database can be overridden using <<fblangref40-ddl-db-alter,`ALTER DATABASE`>>.