Help: Add `.. versionadded` directives to commands documentation

This change ony concerns directives that appear in the document body.

The guidelines for inserting version directives:

 * Baseline version is CMake 3.0, i.e. directives start at 3.1.
 * Always use `.. versionadded::` directive, avoid ad-hoc version
   references. Exception: policy pages.
 * For new command signatures, put `versionadded` on a separate line
   after the signature.
 * For a group of new signatures in a new document section,
   a single version note at the beginning of the section is sufficient.
 * For new options, put `versionadded` on a separate line before
   option description.
 * If all the option descriptions in the list are short one-liners,
   it's fine to put `versionadded` on the same line as the description.
 * If multiple option descriptions in close proximity would have
   the same ..versionadded directive, consider adding a single
   directive after the list, mentioning all added options.
 * For compact value lists and sub-option lists, put a single
  `versionadded` directive after the list mentioning all additions.
 * When a change is described in a single paragraph, put
   `versionadded` into that paragraph.
 * When only part of the paragraph has changed, separate the changed
   part if it doesn't break the flow. Otherwise, write a follow-up
   clarification paragraph and apply version directive to that.
 * When multiple version directives are close by, order earlier
   additions before later additions.
 * Indent related lists and code blocks to include them in the scope
   of `versionadded` directive.

Issue: #19715

1 files changed, 46 insertions, 12 deletions

diff --git a/Help/command/string.rst b/Help/command/string.rst
index 51f8d821ab..9b459b4df5 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -170,10 +170,12 @@ The following characters have special meaning in regular expressions:
   Matches a pattern on either side of the ``|``
 ``()``
   Saves a matched subexpression, which can be referenced
-  in the ``REGEX REPLACE`` operation. Additionally it is saved
-  by all regular expression-related commands, including
-  e.g. :command:`if(MATCHES)`, in the variables
-  :variable:`CMAKE_MATCH_<n>` for ``<n>`` 0..9.
+  in the ``REGEX REPLACE`` operation.
+
+  .. versionadded:: 3.9
+    All regular expression-related commands, including e.g.
+    :command:`if(MATCHES)`, save subgroup matches in the variables
+    :variable:`CMAKE_MATCH_<n>` for ``<n>`` 0..9.
 
 ``*``, ``+`` and ``?`` have higher precedence than concatenation.  ``|``
 has lower precedence than concatenation.  This means that the regular
@@ -205,6 +207,8 @@ Manipulation
 
   string(APPEND <string_variable> [<input>...])
 
+.. versionadded:: 3.4
+
 Append all the ``<input>`` arguments to the string.
 
 .. _PREPEND:
@@ -213,6 +217,8 @@ Append all the ``<input>`` arguments to the string.
 
   string(PREPEND <string_variable> [<input>...])
 
+.. versionadded:: 3.10
+
 Prepend all the ``<input>`` arguments to the string.
 
 .. _CONCAT:
@@ -230,6 +236,8 @@ the result in the named ``<output_variable>``.
 
   string(JOIN <glue> <output_variable> [<input>...])
 
+.. versionadded:: 3.12
+
 Join all the ``<input>`` arguments together using the ``<glue>``
 string and store the result in the named ``<output_variable>``.
 
@@ -271,16 +279,15 @@ result stored in ``<output_variable>`` will *not* be the number of characters.
 
 Store in an ``<output_variable>`` a substring of a given ``<string>``.  If
 ``<length>`` is ``-1`` the remainder of the string starting at ``<begin>``
-will be returned.  If ``<string>`` is shorter than ``<length>`` then the
-end of the string is used instead.
+will be returned.
+
+.. versionadded:: 3.2
+  If ``<string>`` is shorter than ``<length>`` then the end of the string
+  is used instead.  Previous versions of CMake reported an error in this case.
 
 Both ``<begin>`` and ``<length>`` are counted in bytes, so care must
 be exercised if ``<string>`` could contain multi-byte characters.
 
-.. note::
-  CMake 3.1 and below reported an error if ``<length>`` pointed past
-  the end of ``<string>``.
-
 .. _STRIP:
 
 .. code-block:: cmake
@@ -296,6 +303,8 @@ leading and trailing spaces removed.
 
   string(GENEX_STRIP <string> <output_variable>)
 
+.. versionadded:: 3.1
+
 Strip any :manual:`generator expressions <cmake-generator-expressions(7)>`
 from the input ``<string>`` and store the result in the ``<output_variable>``.
 
@@ -305,6 +314,8 @@ from the input ``<string>`` and store the result in the ``<output_variable>``.
 
   string(REPEAT <string> <count> <output_variable>)
 
+.. versionadded:: 3.15
+
 Produce the output string as the input ``<string>`` repeated ``<count>`` times.
 
 Comparison
@@ -323,6 +334,9 @@ Comparison
 
 Compare the strings and store true or false in the ``<output_variable>``.
 
+.. versionadded:: 3.7
+  Added ``LESS_EQUAL`` and ``GREATER_EQUAL`` options.
+
 .. _`Supported Hash Algorithms`:
 
 Hashing
@@ -358,6 +372,9 @@ The supported ``<HASH>`` algorithm names are:
 ``SHA3_512``
   Keccak SHA-3.
 
+.. versionadded:: 3.8
+  Added ``SHA3`` hash algorithms.
+
 Generation
 ^^^^^^^^^^
 
@@ -375,6 +392,8 @@ Convert all numbers into corresponding ASCII characters.
 
   string(HEX <string> <output_variable>)
 
+.. versionadded:: 3.18
+
 Convert each byte in the input ``<string>`` to its hexadecimal representation
 and store the concatenated hex digits in the ``<output_variable>``. Letters in
 the output (``a`` through ``f``) are in lowercase.
@@ -451,6 +470,18 @@ specifiers:
    %y        The last two digits of the current year (00-99)
    %Y        The current year.
 
+.. versionadded:: 3.6
+  ``%s`` format specifier (UNIX time).
+
+.. versionadded:: 3.7
+  ``%a`` and ``%b`` format specifiers (abbreviated month and weekday names).
+
+.. versionadded:: 3.8
+  ``%%`` specifier (literal ``%``).
+
+.. versionadded:: 3.7
+  ``%A`` and ``%B`` format specifiers (full month and weekday names).
+
 Unknown format specifiers will be ignored and copied to the output
 as-is.
 
@@ -461,8 +492,7 @@ If no explicit ``<format_string>`` is given, it will default to:
    %Y-%m-%dT%H:%M:%S    for local time.
    %Y-%m-%dT%H:%M:%SZ   for UTC.
 
-.. note::
-
+.. versionadded:: 3.8
   If the ``SOURCE_DATE_EPOCH`` environment variable is set,
   its value will be used instead of the current time.
   See https://reproducible-builds.org/specs/source-date-epoch/ for details.
@@ -474,6 +504,8 @@ If no explicit ``<format_string>`` is given, it will default to:
   string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
          TYPE <MD5|SHA1> [UPPER])
 
+.. versionadded:: 3.1
+
 Create a universally unique identifier (aka GUID) as per RFC4122
 based on the hash of the combined values of ``<namespace>``
 (which itself has to be a valid UUID) and ``<name>``.
@@ -489,6 +521,8 @@ with the optional ``UPPER`` flag.
 JSON
 ^^^^
 
+.. versionadded:: 3.19
+
 Functionality for querying a JSON string.
 
 .. note::