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

Help/command/install.rst

@@ -1,19 +1,19 @@
 install
 -------
 
-.. only:: html
-
-   .. contents::
-
 Specify rules to run at install time.
 
-This command accepts several signatures:
+Synopsis
+^^^^^^^^
 
-* :ref:`install(TARGETS) <install-targets>`
-* :ref:`install(FILES|PROGRAMS) <install-files>`
-* :ref:`install(DIRECTORY) <install-directory>`
-* :ref:`install(SCRIPT|CODE) <install-script>`
-* :ref:`install(EXPORT|EXPORT_ANDROID_MK) <install-export>`
+.. parsed-literal::
+
+  install(`TARGETS`_ <target>... [...])
+  install({`FILES`_ | `PROGRAMS`_} <file>... DESTINATION <dir> [...])
+  install(`DIRECTORY`_ <dir>... DESTINATION <dir> [...])
+  install(`SCRIPT`_ <file> [...])
+  install(`CODE`_ <code> [...])
+  install(`EXPORT`_ <export-name> DESTINATION <dir> [...])
 
 Introduction
 ^^^^^^^^^^^^
@@ -89,11 +89,11 @@ Command signatures that install files may print messages during
 installation.  Use the :variable:`CMAKE_INSTALL_MESSAGE` variable
 to control which messages are printed.
 
-.. _install-targets:
-
 Installing Targets
 ^^^^^^^^^^^^^^^^^^
 
+.. _TARGETS:
+
 ::
 
   install(TARGETS targets... [EXPORT <export-name>]
@@ -284,11 +284,12 @@ The install destination given to the target install ``DESTINATION`` may
 use "generator expressions" with the syntax ``$<...>``.  See the
 :manual:`cmake-generator-expressions(7)` manual for available expressions.
 
-.. _install-files:
-
 Installing Files
 ^^^^^^^^^^^^^^^^
 
+.. _FILES:
+.. _PROGRAMS:
+
 ::
 
   install(<FILES|PROGRAMS> files... DESTINATION <dir>
@@ -319,11 +320,11 @@ The install destination given to the files install ``DESTINATION`` may
 use "generator expressions" with the syntax ``$<...>``.  See the
 :manual:`cmake-generator-expressions(7)` manual for available expressions.
 
-.. _install-directory:
-
 Installing Directories
 ^^^^^^^^^^^^^^^^^^^^^^
 
+.. _DIRECTORY:
+
 ::
 
   install(DIRECTORY dirs... DESTINATION <dir>
@@ -402,11 +403,12 @@ given to the directory install ``DESTINATION`` may use "generator expressions"
 with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.
 
-.. _install-script:
-
 Custom Installation Logic
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. _CODE:
+.. _SCRIPT:
+
 ::
 
   install([[SCRIPT <file>] [CODE <code>]]
@@ -425,11 +427,11 @@ example, the code
 
 will print a message during installation.
 
-.. _install-export:
-
 Installing Exports
 ^^^^^^^^^^^^^^^^^^
 
+.. _EXPORT:
+
 ::
 
   install(EXPORT <export-name> DESTINATION <dir>

Help/command/list.rst

@@ -1,11 +1,37 @@
 list
 ----
 
-.. only:: html
+List operations.
 
-   .. contents::
+Synopsis
+^^^^^^^^
 
-List operations.
+.. parsed-literal::
+
+  `Reading`_
+    list(`LENGTH`_ <list> <out-var>)
+    list(`GET`_ <list> <element index> [<index> ...] <out-var>)
+    list(`JOIN`_ <list> <glue> <out-var>)
+    list(`SUBLIST`_ <list> <begin> <length> <out-var>)
+
+  `Search`_
+    list(`FIND`_ <list> <value> <out-var>)
+
+  `Modification`_
+    list(`APPEND`_ <list> [<element>...])
+    list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>)
+    list(`INSERT`_ <list> <index> [<element>...])
+    list(`REMOVE_ITEM`_ <list> <value>...)
+    list(`REMOVE_AT`_ <list> <index>...)
+    list(`REMOVE_DUPLICATES`_ <list>)
+    list(`TRANSFORM`_ <list> <ACTION> [...])
+
+  `Ordering`_
+    list(`REVERSE`_ <list>)
+    list(`SORT`_ <list>)
+
+Introduction
+^^^^^^^^^^^^
 
 The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``,
 ``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create
@@ -36,8 +62,7 @@ scope.  To propagate the results of these operations upwards, use
 Reading
 ^^^^^^^
 
-LENGTH
-""""""
+.. _LENGTH:
 
 ::
 
@@ -45,8 +70,7 @@ LENGTH
 
 Returns the list's length.
 
-GET
-"""
+.. _GET:
 
 ::
 
@@ -54,8 +78,7 @@ GET
 
 Returns the list of elements specified by indices from the list.
 
-JOIN
-""""
+.. _JOIN:
 
 ::
 
@@ -65,8 +88,7 @@ Returns a string joining all list's elements using the glue string.
 To join multiple strings, which are not part of a list, use ``JOIN`` operator
 from :command:`string` command.
 
-SUBLIST
-"""""""
+.. _SUBLIST:
 
 ::
 
@@ -80,8 +102,7 @@ the remaining elements of the list starting at ``<begin>`` will be returned.
 Search
 ^^^^^^
 
-FIND
-""""
+.. _FIND:
 
 ::
 
@@ -93,8 +114,7 @@ if it wasn't found.
 Modification
 ^^^^^^^^^^^^
 
-APPEND
-""""""
+.. _APPEND:
 
 ::
 
@@ -102,8 +122,7 @@ APPEND
 
 Appends elements to the list.
 
-FILTER
-""""""
+.. _FILTER:
 
 ::
 
@@ -115,8 +134,7 @@ In ``REGEX`` mode, items will be matched against the given regular expression.
 For more information on regular expressions see also the
 :command:`string` command.
 
-INSERT
-""""""
+.. _INSERT:
 
 ::
 
@@ -124,8 +142,7 @@ INSERT
 
 Inserts elements to the list to the specified location.
 
-REMOVE_ITEM
-"""""""""""
+.. _REMOVE_ITEM:
 
 ::
 
@@ -133,8 +150,7 @@ REMOVE_ITEM
 
 Removes the given items from the list.
 
-REMOVE_AT
-"""""""""
+.. _REMOVE_AT:
 
 ::
 
@@ -142,8 +158,7 @@ REMOVE_AT
 
 Removes items at given indices from the list.
 
-REMOVE_DUPLICATES
-"""""""""""""""""
+.. _REMOVE_DUPLICATES:
 
 ::
 
@@ -151,8 +166,7 @@ REMOVE_DUPLICATES
 
 Removes duplicated items in the list.
 
-TRANSFORM
-"""""""""
+.. _TRANSFORM:
 
 ::
 
@@ -224,11 +238,10 @@ expression will be transformed. ::
   list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
 
 
-Sorting
-^^^^^^^
+Ordering
+^^^^^^^^
 
-REVERSE
-"""""""
+.. _REVERSE:
 
 ::
 
@@ -236,8 +249,7 @@ REVERSE
 
 Reverses the contents of the list in-place.
 
-SORT
-""""
+.. _SORT:
 
 ::
 

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:
 
 ::