Help: Add Synopsis section to install, list, and string docs

Summarize the command signatures in one block at the top of the
documentation as is typical in Unix command-line tool manuals.
Make the mode keywords links to the corresponding full signature
and documentation.

Issue: #17948

1 files changed, 65 insertions, 46 deletions

diff --git a/Help/command/string.rst b/Help/command/string.rst
index e84f788..efa923b 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -1,17 +1,52 @@
 string
 ------
 
-.. only:: html
-
-   .. contents::
-
 String operations.
 
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+  `Search and Replace`_
+    string(`FIND`_ <string> <substring> <out-var> [...])
+    string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...)
+
+  `Regular Expressions`_
+    string(`REGEX MATCH`_ <match-regex> <out-var> <input>...)
+    string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...)
+    string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...)
+
+  `Manipulation`_
+    string(`APPEND`_ <string-var> [<input>...])
+    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(`LENGTH`_ <string> <out-var>)
+    string(`SUBSTRING`_ <string> <begin> <length> <out-var>)
+    string(`STRIP`_ <string> <out-var>)
+    string(`GENEX_STRIP`_ <string> <out-var>)
+
+  `Comparison`_
+    string(`COMPARE`_ <op> <string1> <string2> <out-var>)
+
+  `Hashing`_
+    string(`\<HASH\> <HASH_>`_ <out-var> <input>)
+
+  `Generation`_
+    string(`ASCII`_ <number>... <out-var>)
+    string(`CONFIGURE`_ <string1> <out-var> [...])
+    string(`MAKE_C_IDENTIFIER`_ <string> <out-var>)
+    string(`RANDOM`_ [<option>...] <out-var>)
+    string(`TIMESTAMP`_ <out-var> [<format string>] [UTC])
+    string(`UUID`_ <out-var> ...)
+
 Search and Replace
 ^^^^^^^^^^^^^^^^^^
 
-FIND
-""""
+.. _FIND:
 
 ::
 
@@ -22,8 +57,7 @@ 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.
 
-REPLACE
-"""""""
+.. _REPLACE:
 
 ::
 
@@ -37,8 +71,7 @@ with ``replace_string`` and store the result in the output.
 Regular Expressions
 ^^^^^^^^^^^^^^^^^^^
 
-REGEX MATCH
-"""""""""""
+.. _`REGEX MATCH`:
 
 ::
 
@@ -48,8 +81,7 @@ REGEX MATCH
 Match the regular expression once and store the match in the output variable.
 All ``<input>`` arguments are concatenated before matching.
 
-REGEX MATCHALL
-""""""""""""""
+.. _`REGEX MATCHALL`:
 
 ::
 
@@ -60,8 +92,7 @@ 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
-"""""""""""""
+.. _`REGEX REPLACE`:
 
 ::
 
@@ -123,8 +154,7 @@ expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``.
 Manipulation
 ^^^^^^^^^^^^
 
-APPEND
-""""""
+.. _APPEND:
 
 ::
 
@@ -132,8 +162,7 @@ APPEND
 
 Append all the input arguments to the string.
 
-PREPEND
-"""""""
+.. _PREPEND:
 
 ::
 
@@ -141,8 +170,7 @@ PREPEND
 
 Prepend all the input arguments to the string.
 
-CONCAT
-""""""
+.. _CONCAT:
 
 ::
 
@@ -151,8 +179,7 @@ CONCAT
 Concatenate all the input arguments together and store
 the result in the named output variable.
 
-JOIN
-""""
+.. _JOIN:
 
 ::
 
@@ -165,8 +192,7 @@ To join list's elements, use preferably the ``JOIN`` operator
 from :command:`list` command. This allows for the elements to have
 special characters like ``;`` in them.
 
-TOLOWER
-"""""""
+.. _TOLOWER:
 
 ::
 
@@ -174,8 +200,7 @@ TOLOWER
 
 Convert string to lower characters.
 
-TOUPPER
-"""""""
+.. _TOUPPER:
 
 ::
 
@@ -183,8 +208,7 @@ TOUPPER
 
 Convert string to upper characters.
 
-LENGTH
-""""""
+.. _LENGTH:
 
 ::
 
@@ -192,8 +216,7 @@ LENGTH
 
 Store in an output variable a given string's length.
 
-SUBSTRING
-"""""""""
+.. _SUBSTRING:
 
 ::
 
@@ -207,8 +230,7 @@ If string is shorter than length then end of string is used instead.
   CMake 3.1 and below reported an error if length pointed past
   the end of string.
 
-STRIP
-"""""
+.. _STRIP:
 
 ::
 
@@ -217,8 +239,7 @@ STRIP
 Store in an output variable a substring of a given string with leading and
 trailing spaces removed.
 
-GENEX_STRIP
-"""""""""""
+.. _GENEX_STRIP:
 
 ::
 
@@ -230,6 +251,8 @@ from the ``input string`` and store the result in the ``output variable``.
 Comparison
 ^^^^^^^^^^
 
+.. _COMPARE:
+
 ::
 
   string(COMPARE LESS <string1> <string2> <output variable>)
@@ -246,6 +269,8 @@ Compare the strings and store true or false in the output variable.
 Hashing
 ^^^^^^^
 
+.. _`HASH`:
+
 ::
 
   string(<HASH> <output variable> <input>)
@@ -277,8 +302,7 @@ The supported ``<HASH>`` algorithm names are:
 Generation
 ^^^^^^^^^^
 
-ASCII
-"""""
+.. _ASCII:
 
 ::
 
@@ -286,8 +310,7 @@ ASCII
 
 Convert all numbers into corresponding ASCII characters.
 
-CONFIGURE
-"""""""""
+.. _CONFIGURE:
 
 ::
 
@@ -296,8 +319,7 @@ CONFIGURE
 
 Transform a string like :command:`configure_file` transforms a file.
 
-MAKE_C_IDENTIFIER
-"""""""""""""""""
+.. _MAKE_C_IDENTIFIER:
 
 ::
 
@@ -308,8 +330,7 @@ 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
-""""""
+.. _RANDOM:
 
 ::
 
@@ -322,8 +343,7 @@ 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.
 
-TIMESTAMP
-"""""""""
+.. _TIMESTAMP:
 
 ::
 
@@ -378,8 +398,7 @@ If no explicit ``<format string>`` is given it will default to:
   its value will be used instead of the current time.
   See https://reproducible-builds.org/specs/source-date-epoch/ for details.
 
-UUID
-""""
+.. _UUID:
 
 ::