From 26cd64d9776aa418d0083374084ff7738422b4c4 Mon Sep 17 00:00:00 2001
From: Craig Scott <craig.scott@crascit.com>
Date: Tue, 16 Jul 2019 22:03:15 +1000
Subject: Help: Fix language and formatting inconsistencies for string()
 command

---
 Help/command/string.rst | 166 +++++++++++++++++++++++++-----------------------
 1 file changed, 85 insertions(+), 81 deletions(-)

diff --git a/Help/command/string.rst b/Help/command/string.rst
index 2e89d7b..c0d83f8 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -22,8 +22,8 @@ Synopsis
     string(`PREPEND`_ <string-var> [<input>...])
     string(`CONCAT`_ <out-var> [<input>...])
     string(`JOIN`_ <glue> <out-var> [<input>...])
-    string(`TOLOWER`_ <string1> <out-var>)
-    string(`TOUPPER`_ <string1> <out-var>)
+    string(`TOLOWER`_ <string> <out-var>)
+    string(`TOUPPER`_ <string> <out-var>)
     string(`LENGTH`_ <string> <out-var>)
     string(`SUBSTRING`_ <string> <begin> <length> <out-var>)
     string(`STRIP`_ <string> <out-var>)
@@ -38,7 +38,7 @@ Synopsis
 
   `Generation`_
     string(`ASCII`_ <number>... <out-var>)
-    string(`CONFIGURE`_ <string1> <out-var> [...])
+    string(`CONFIGURE`_ <string> <out-var> [...])
     string(`MAKE_C_IDENTIFIER`_ <string> <out-var>)
     string(`RANDOM`_ [<option>...] <out-var>)
     string(`TIMESTAMP`_ <out-var> [<format string>] [UTC])
@@ -51,23 +51,24 @@ Search and Replace
 
 .. code-block:: cmake
 
-  string(FIND <string> <substring> <output variable> [REVERSE])
+  string(FIND <string> <substring> <output_variable> [REVERSE])
 
-Return the position where the given substring was found in
-the supplied string.  If the ``REVERSE`` flag was used, the command will
+Return the position where the given ``<substring>`` was found in
+the supplied ``<string>``.  If the ``REVERSE`` flag was used, the command will
 search for the position of the last occurrence of the specified
-substring.  If the substring is not found, a position of -1 is returned.
+``<substring>``.  If the ``<substring>`` is not found, a position of -1 is
+returned.
 
 .. _REPLACE:
 
 .. code-block:: cmake
 
   string(REPLACE <match_string>
-         <replace_string> <output variable>
+         <replace_string> <output_variable>
          <input> [<input>...])
 
-Replace all occurrences of ``match_string`` in the input
-with ``replace_string`` and store the result in the output.
+Replace all occurrences of ``<match_string>`` in the ``<input>``
+with ``<replace_string>`` and store the result in the ``<output_variable>``.
 
 Regular Expressions
 ^^^^^^^^^^^^^^^^^^^
@@ -77,9 +78,10 @@ Regular Expressions
 .. code-block:: cmake
 
   string(REGEX MATCH <regular_expression>
-         <output variable> <input> [<input>...])
+         <output_variable> <input> [<input>...])
 
-Match the regular expression once and store the match in the output variable.
+Match the ``<regular_expression>`` once and store the match in the
+``<output_variable>``.
 All ``<input>`` arguments are concatenated before matching.
 
 .. _`REGEX MATCHALL`:
@@ -87,10 +89,10 @@ All ``<input>`` arguments are concatenated before matching.
 .. code-block:: cmake
 
   string(REGEX MATCHALL <regular_expression>
-         <output variable> <input> [<input>...])
+         <output_variable> <input> [<input>...])
 
-Match the regular expression as many times as possible and store the matches
-in the output variable as a list.
+Match the ``<regular_expression>`` as many times as possible and store the
+matches in the ``<output_variable>`` as a list.
 All ``<input>`` arguments are concatenated before matching.
 
 .. _`REGEX REPLACE`:
@@ -98,16 +100,17 @@ All ``<input>`` arguments are concatenated before matching.
 .. code-block:: cmake
 
   string(REGEX REPLACE <regular_expression>
-         <replace_expression> <output variable>
+         <replacement_expression> <output_variable>
          <input> [<input>...])
 
-Match the regular expression as many times as possible and substitute the
-replacement expression for the match in the output.
+Match the ``<regular_expression>`` as many times as possible and substitute
+the ``<replacement_expression>`` for the match in the output.
 All ``<input>`` arguments are concatenated before matching.
 
-The replace expression may refer to paren-delimited subexpressions of the
-match using ``\1``, ``\2``, ..., ``\9``.  Note that two backslashes (``\\1``)
-are required in CMake code to get a backslash through argument parsing.
+The ``<replacement_expression>`` may refer to parenthesis-delimited
+subexpressions of the match using ``\1``, ``\2``, ..., ``\9``.  Note that
+two backslashes (``\\1``) are required in CMake code to get a backslash
+through argument parsing.
 
 .. _`Regex Specification`:
 
@@ -180,103 +183,104 @@ Manipulation
 
 .. code-block:: cmake
 
-  string(APPEND <string variable> [<input>...])
+  string(APPEND <string_variable> [<input>...])
 
-Append all the input arguments to the string.
+Append all the ``<input>`` arguments to the string.
 
 .. _PREPEND:
 
 .. code-block:: cmake
 
-  string(PREPEND <string variable> [<input>...])
+  string(PREPEND <string_variable> [<input>...])
 
-Prepend all the input arguments to the string.
+Prepend all the ``<input>`` arguments to the string.
 
 .. _CONCAT:
 
 .. code-block:: cmake
 
-  string(CONCAT <output variable> [<input>...])
+  string(CONCAT <output_variable> [<input>...])
 
-Concatenate all the input arguments together and store
-the result in the named output variable.
+Concatenate all the ``<input>`` arguments together and store
+the result in the named ``<output_variable>``.
 
 .. _JOIN:
 
 .. code-block:: cmake
 
-  string(JOIN <glue> <output variable> [<input>...])
+  string(JOIN <glue> <output_variable> [<input>...])
 
-Join all the input arguments together using the glue
-string and store the result in the named output variable.
+Join all the ``<input>`` arguments together using the ``<glue>``
+string and store the result in the named ``<output_variable>``.
 
-To join list's elements, use preferably the ``JOIN`` operator
-from :command:`list` command. This allows for the elements to have
+To join a list's elements, prefer to use the ``JOIN`` operator
+from the :command:`list` command.  This allows for the elements to have
 special characters like ``;`` in them.
 
 .. _TOLOWER:
 
 .. code-block:: cmake
 
-  string(TOLOWER <string1> <output variable>)
+  string(TOLOWER <string> <output_variable>)
 
-Convert string to lower characters.
+Convert ``<string>`` to lower characters.
 
 .. _TOUPPER:
 
 .. code-block:: cmake
 
-  string(TOUPPER <string1> <output variable>)
+  string(TOUPPER <string> <output_variable>)
 
-Convert string to upper characters.
+Convert ``<string>`` to upper characters.
 
 .. _LENGTH:
 
 .. code-block:: cmake
 
-  string(LENGTH <string> <output variable>)
+  string(LENGTH <string> <output_variable>)
 
-Store in an output variable a given string's length.
+Store in an ``<output_variable>`` a given string's length.
 
 .. _SUBSTRING:
 
 .. code-block:: cmake
 
-  string(SUBSTRING <string> <begin> <length> <output variable>)
+  string(SUBSTRING <string> <begin> <length> <output_variable>)
 
-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 end of string is used instead.
+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.
 
 .. note::
-  CMake 3.1 and below reported an error if length pointed past
-  the end of string.
+  CMake 3.1 and below reported an error if ``<length>`` pointed past
+  the end of ``<string>``.
 
 .. _STRIP:
 
 .. code-block:: cmake
 
-  string(STRIP <string> <output variable>)
+  string(STRIP <string> <output_variable>)
 
-Store in an output variable a substring of a given string with leading and
-trailing spaces removed.
+Store in an ``<output_variable>`` a substring of a given ``<string>`` with
+leading and trailing spaces removed.
 
 .. _GENEX_STRIP:
 
 .. code-block:: cmake
 
-  string(GENEX_STRIP <input string> <output variable>)
+  string(GENEX_STRIP <string> <output_variable>)
 
 Strip any :manual:`generator expressions <cmake-generator-expressions(7)>`
-from the ``input string`` and store the result in the ``output variable``.
+from the input ``<string>`` and store the result in the ``<output_variable>``.
 
 .. _REPEAT:
 
 .. code-block:: cmake
 
-  string(REPEAT <input string> <count> <output variable>)
+  string(REPEAT <string> <count> <output_variable>)
 
-Produce the output string as repetion of ``input string`` ``count`` times.
+Produce the output string as the input ``<string>`` repeated ``<count>`` times.
 
 Comparison
 ^^^^^^^^^^
@@ -285,14 +289,14 @@ Comparison
 
 .. code-block:: cmake
 
-  string(COMPARE LESS <string1> <string2> <output variable>)
-  string(COMPARE GREATER <string1> <string2> <output variable>)
-  string(COMPARE EQUAL <string1> <string2> <output variable>)
-  string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
-  string(COMPARE LESS_EQUAL <string1> <string2> <output variable>)
-  string(COMPARE GREATER_EQUAL <string1> <string2> <output variable>)
+  string(COMPARE LESS <string1> <string2> <output_variable>)
+  string(COMPARE GREATER <string1> <string2> <output_variable>)
+  string(COMPARE EQUAL <string1> <string2> <output_variable>)
+  string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
+  string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
+  string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
 
-Compare the strings and store true or false in the output variable.
+Compare the strings and store true or false in the ``<output_variable>``.
 
 .. _`Supported Hash Algorithms`:
 
@@ -303,9 +307,9 @@ Hashing
 
 .. code-block:: cmake
 
-  string(<HASH> <output variable> <input>)
+  string(<HASH> <output_variable> <input>)
 
-Compute a cryptographic hash of the input string.
+Compute a cryptographic hash of the ``<input>`` string.
 The supported ``<HASH>`` algorithm names are:
 
 ``MD5``
@@ -336,7 +340,7 @@ Generation
 
 .. code-block:: cmake
 
-  string(ASCII <number> [<number> ...] <output variable>)
+  string(ASCII <number> [<number> ...] <output_variable>)
 
 Convert all numbers into corresponding ASCII characters.
 
@@ -344,31 +348,31 @@ Convert all numbers into corresponding ASCII characters.
 
 .. code-block:: cmake
 
-  string(CONFIGURE <string1> <output variable>
+  string(CONFIGURE <string> <output_variable>
          [@ONLY] [ESCAPE_QUOTES])
 
-Transform a string like :command:`configure_file` transforms a file.
+Transform a ``<string>`` like :command:`configure_file` transforms a file.
 
 .. _MAKE_C_IDENTIFIER:
 
 .. code-block:: cmake
 
-  string(MAKE_C_IDENTIFIER <input string> <output variable>)
+  string(MAKE_C_IDENTIFIER <string> <output_variable>)
 
-Convert each non-alphanumeric character in the ``<input string>`` to an
-underscore and store the result in the ``<output variable>``.  If the first
-character of the string is a digit, an underscore will also be prepended to
-the result.
+Convert each non-alphanumeric character in the input ``<string>`` to an
+underscore and store the result in the ``<output_variable>``.  If the first
+character of the ``<string>`` is a digit, an underscore will also be prepended
+to the result.
 
 .. _RANDOM:
 
 .. code-block:: cmake
 
   string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
-         [RANDOM_SEED <seed>] <output variable>)
+         [RANDOM_SEED <seed>] <output_variable>)
 
-Return a random string of given length consisting of
-characters from the given alphabet.  Default length is 5 characters
+Return a random string of given ``<length>`` consisting of
+characters from the given ``<alphabet>``.  Default length is 5 characters
 and default alphabet is all numbers and upper and lower case letters.
 If an integer ``RANDOM_SEED`` is given, its value will be used to seed the
 random number generator.
@@ -377,18 +381,18 @@ random number generator.
 
 .. code-block:: cmake
 
-  string(TIMESTAMP <output variable> [<format string>] [UTC])
+  string(TIMESTAMP <output_variable> [<format_string>] [UTC])
 
 Write a string representation of the current date
-and/or time to the output variable.
+and/or time to the ``<output_variable>``.
 
-Should the command be unable to obtain a timestamp the output variable
-will be set to the empty string "".
+If the command is unable to obtain a timestamp, the ``<output_variable>``
+will be set to the empty string ``""``.
 
 The optional ``UTC`` flag requests the current date/time representation to
 be in Coordinated Universal Time (UTC) rather than local time.
 
-The optional ``<format string>`` may contain the following format
+The optional ``<format_string>`` may contain the following format
 specifiers:
 
 ::
@@ -415,7 +419,7 @@ specifiers:
 Unknown format specifiers will be ignored and copied to the output
 as-is.
 
-If no explicit ``<format string>`` is given it will default to:
+If no explicit ``<format_string>`` is given, it will default to:
 
 ::
 
@@ -432,7 +436,7 @@ If no explicit ``<format string>`` is given it will default to:
 
 .. code-block:: cmake
 
-  string(UUID <output variable> NAMESPACE <namespace> NAME <name>
+  string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
          TYPE <MD5|SHA1> [UPPER])
 
 Create a universally unique identifier (aka GUID) as per RFC4122
@@ -441,6 +445,6 @@ based on the hash of the combined values of ``<namespace>``
 The hash algorithm can be either ``MD5`` (Version 3 UUID) or
 ``SHA1`` (Version 5 UUID).
 A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``
-where each `x` represents a lower case hexadecimal character.
-Where required an uppercase representation can be requested
+where each ``x`` represents a lower case hexadecimal character.
+Where required, an uppercase representation can be requested
 with the optional ``UPPER`` flag.
-- 
cgit v0.12


From b97673f54ba0fad406f73c4790d5dd94beced6f9 Mon Sep 17 00:00:00 2001
From: Craig Scott <craig.scott@crascit.com>
Date: Fri, 19 Jul 2019 20:35:40 +1000
Subject: Help: Add note to each string() subcommand that assumes ASCII input

Fixes: #19465
---
 Help/command/string.rst | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/Help/command/string.rst b/Help/command/string.rst
index c0d83f8..81a2061 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -59,6 +59,10 @@ search for the position of the last occurrence of the specified
 ``<substring>``.  If the ``<substring>`` is not found, a position of -1 is
 returned.
 
+The ``string(FIND)`` subcommand treats all strings as ASCII-only characters.
+The index stored in ``<output_variable>`` will also be counted in bytes,
+so strings containing multi-byte characters may lead to unexpected results.
+
 .. _REPLACE:
 
 .. code-block:: cmake
@@ -239,7 +243,9 @@ Convert ``<string>`` to upper characters.
 
   string(LENGTH <string> <output_variable>)
 
-Store in an ``<output_variable>`` a given string's length.
+Store in an ``<output_variable>`` a given string's length in bytes.
+Note that this means if ``<string>`` contains multi-byte characters, the
+result stored in ``<output_variable>`` will *not* be the number of characters.
 
 .. _SUBSTRING:
 
@@ -252,6 +258,9 @@ Store in an ``<output_variable>`` a substring of a given ``<string>``.  If
 will be returned.  If ``<string>`` is shorter than ``<length>`` then the
 end of the string is used instead.
 
+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>``.
-- 
cgit v0.12