Merge topic 'doc-command-synopsis'

72814e46da Utilities/Sphinx: Make HTML links in parsed-literal blocks more obvious
08b4ea639c Help: Organize file command docs into sections
51c0e1407c Help: Add Synopsis section to install, list, and string docs
0acd705119 Help: Improve list command signature group name for read operations
d5b2745b34 Help: Re-order file command docs
7d918b3cee cmRST: Parse inline links and inline literals

Acked-by: Kitware Robot <[email protected]>
Merge-request: !2039

Help/command/file.rst

@@ -3,23 +3,44 @@ file
 
 File manipulation command.
 
-------------------------------------------------------------------------------
+Synopsis
+^^^^^^^^
 
-::
+.. parsed-literal::
 
-  file(WRITE <filename> <content>...)
-  file(APPEND <filename> <content>...)
+  `Reading`_
+    file(`READ`_ <filename> <out-var> [...])
+    file(`STRINGS`_ <filename> <out-var> [...])
+    file(`\<HASH\> <HASH_>`_ <filename> <out-var>)
+    file(`TIMESTAMP`_ <filename> <out-var> [...])
 
-Write ``<content>`` into a file called ``<filename>``.  If the file does
-not exist, it will be created.  If the file already exists, ``WRITE``
-mode will overwrite it and ``APPEND`` mode will append to the end.
-Any directories in the path specified by ``<filename>`` that do not
-exist will be created.
+  `Writing`_
+    file({`WRITE`_ | `APPEND`_} <filename> <content>...)
+    file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...])
+    file(`GENERATE`_ OUTPUT <output-file> [...])
 
-If the file is a build input, use the :command:`configure_file` command
-to update the file only when its content changes.
+  `Filesystem`_
+    file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...])
+    file(`RENAME`_ <oldname> <newname>)
+    file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...])
+    file(`MAKE_DIRECTORY`_ [<dir>...])
+    file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...])
+
+  `Path Conversion`_
+    file(`RELATIVE_PATH`_ <out-var> <directory> <file>)
+    file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>)
+
+  `Transfer`_
+    file(`DOWNLOAD`_ <url> <file> [...])
+    file(`UPLOAD`_ <file> <url> [...])
 
-------------------------------------------------------------------------------
+  `Locking`_
+    file(`LOCK`_ <path> [...])
+
+Reading
+^^^^^^^
+
+.. _READ:
 
 ::
 
@@ -31,7 +52,7 @@ Read content from a file called ``<filename>`` and store it in a
 read at most ``<max-in>`` bytes.  The ``HEX`` option causes data to
 be converted to a hexadecimal representation (useful for binary data).
 
-------------------------------------------------------------------------------
+.. _STRINGS:
 
 ::
 
@@ -82,7 +103,7 @@ For example, the code
 stores a list in the variable ``myfile`` in which each item is a line
 from the input file.
 
-------------------------------------------------------------------------------
+.. _HASH:
 
 ::
 
@@ -93,7 +114,108 @@ store it in a ``<variable>``.  The supported ``<HASH>`` algorithm names
 are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>`
 command.
 
-------------------------------------------------------------------------------
+.. _TIMESTAMP:
+
+::
+
+  file(TIMESTAMP <filename> <variable> [<format>] [UTC])
+
+Compute a string representation of the modification time of ``<filename>``
+and store it in ``<variable>``.  Should the command be unable to obtain a
+timestamp variable will be set to the empty string ("").
+
+See the :command:`string(TIMESTAMP)` command for documentation of
+the ``<format>`` and ``UTC`` options.
+
+Writing
+^^^^^^^
+
+.. _WRITE:
+.. _APPEND:
+
+::
+
+  file(WRITE <filename> <content>...)
+  file(APPEND <filename> <content>...)
+
+Write ``<content>`` into a file called ``<filename>``.  If the file does
+not exist, it will be created.  If the file already exists, ``WRITE``
+mode will overwrite it and ``APPEND`` mode will append to the end.
+Any directories in the path specified by ``<filename>`` that do not
+exist will be created.
+
+If the file is a build input, use the :command:`configure_file` command
+to update the file only when its content changes.
+
+.. _TOUCH:
+.. _TOUCH_NOCREATE:
+
+::
+
+  file(TOUCH [<files>...])
+  file(TOUCH_NOCREATE [<files>...])
+
+Create a file with no content if it does not yet exist. If the file already
+exists, its access and/or modification will be updated to the time when the
+function call is executed.
+
+Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file
+does not exist it will be silently ignored.
+
+With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be
+modified.
+
+.. _GENERATE:
+
+::
+
+  file(GENERATE OUTPUT output-file
+       <INPUT input-file|CONTENT content>
+       [CONDITION expression])
+
+Generate an output file for each build configuration supported by the current
+:manual:`CMake Generator <cmake-generators(7)>`.  Evaluate
+:manual:`generator expressions <cmake-generator-expressions(7)>`
+from the input content to produce the output content.  The options are:
+
+``CONDITION <condition>``
+  Generate the output file for a particular configuration only if
+  the condition is true.  The condition must be either ``0`` or ``1``
+  after evaluating generator expressions.
+
+``CONTENT <content>``
+  Use the content given explicitly as input.
+
+``INPUT <input-file>``
+  Use the content from a given file as input.
+  A relative path is treated with respect to the value of
+  :variable:`CMAKE_CURRENT_SOURCE_DIR`.  See policy :policy:`CMP0070`.
+
+``OUTPUT <output-file>``
+  Specify the output file name to generate.  Use generator expressions
+  such as ``$<CONFIG>`` to specify a configuration-specific output file
+  name.  Multiple configurations may generate the same output file only
+  if the generated content is identical.  Otherwise, the ``<output-file>``
+  must evaluate to an unique name for each configuration.
+  A relative path (after evaluating generator expressions) is treated
+  with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
+  See policy :policy:`CMP0070`.
+
+Exactly one ``CONTENT`` or ``INPUT`` option must be given.  A specific
+``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
+Generated files are modified and their timestamp updated on subsequent cmake
+runs only if their content is changed.
+
+Note also that ``file(GENERATE)`` does not create the output file until the
+generation phase. The output file will not yet have been written when the
+``file(GENERATE)`` command returns, it is written only after processing all
+of a project's ``CMakeLists.txt`` files.
+
+Filesystem
+^^^^^^^^^^
+
+.. _GLOB:
+.. _GLOB_RECURSE:
 
 ::
 
@@ -148,7 +270,7 @@ Examples of recursive globbing include::
 
   /dir/*.py  - match all python files in /dir and subdirectories
 
-------------------------------------------------------------------------------
+.. _RENAME:
 
 ::
 
@@ -157,7 +279,8 @@ Examples of recursive globbing include::
 Move a file or directory within a filesystem from ``<oldname>`` to
 ``<newname>``, replacing the destination atomically.
 
-------------------------------------------------------------------------------
+.. _REMOVE:
+.. _REMOVE_RECURSE:
 
 ::
 
@@ -168,7 +291,7 @@ Remove the given files.  The ``REMOVE_RECURSE`` mode will remove the given
 files and directories, also non-empty directories. No error is emitted if a
 given file does not exist.
 
-------------------------------------------------------------------------------
+.. _MAKE_DIRECTORY:
 
 ::
 
@@ -176,7 +299,44 @@ given file does not exist.
 
 Create the given directories and their parents as needed.
 
-------------------------------------------------------------------------------
+.. _COPY:
+.. _INSTALL:
+
+::
+
+  file(<COPY|INSTALL> <files>... DESTINATION <dir>
+       [FILE_PERMISSIONS <permissions>...]
+       [DIRECTORY_PERMISSIONS <permissions>...]
+       [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
+       [FILES_MATCHING]
+       [[PATTERN <pattern> | REGEX <regex>]
+        [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
+
+The ``COPY`` signature copies files, directories, and symlinks to a
+destination folder.  Relative input paths are evaluated with respect
+to the current source directory, and a relative destination is
+evaluated with respect to the current build directory.  Copying
+preserves input file timestamps, and optimizes out a file if it exists
+at the destination with the same timestamp.  Copying preserves input
+permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
+are given (default is ``USE_SOURCE_PERMISSIONS``).
+
+See the :command:`install(DIRECTORY)` command for documentation of
+permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and
+``EXCLUDE`` options.  Copying directories preserves the structure
+of their content even if options are used to select a subset of
+files.
+
+The ``INSTALL`` signature differs slightly from ``COPY``: it prints
+status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable),
+and ``NO_SOURCE_PERMISSIONS`` is default.
+Installation scripts generated by the :command:`install` command
+use this signature (with some undocumented options for internal use).
+
+Path Conversion
+^^^^^^^^^^^^^^^
+
+.. _RELATIVE_PATH:
 
 ::
 
@@ -185,7 +345,8 @@ Create the given directories and their parents as needed.
 Compute the relative path from a ``<directory>`` to a ``<file>`` and
 store it in the ``<variable>``.
 
-------------------------------------------------------------------------------
+.. _TO_CMAKE_PATH:
+.. _TO_NATIVE_PATH:
 
 ::
 
@@ -203,7 +364,11 @@ path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere).
 Always use double quotes around the ``<path>`` to be sure it is treated
 as a single argument to this command.
 
-------------------------------------------------------------------------------
+Transfer
+^^^^^^^^
+
+.. _DOWNLOAD:
+.. _UPLOAD:
 
 ::
 
@@ -290,116 +455,10 @@ check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content.
 If neither ``TLS`` option is given CMake will check variables
 ``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.
 
-------------------------------------------------------------------------------
-
-::
-
-  file(TOUCH [<files>...])
-  file(TOUCH_NOCREATE [<files>...])
-
-Create a file with no content if it does not yet exist. If the file already
-exists, its access and/or modification will be updated to the time when the
-function call is executed.
-
-Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file
-does not exist it will be silently ignored.
-
-With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be
-modified.
-
-------------------------------------------------------------------------------
-
-::
-
-  file(TIMESTAMP <filename> <variable> [<format>] [UTC])
-
-Compute a string representation of the modification time of ``<filename>``
-and store it in ``<variable>``.  Should the command be unable to obtain a
-timestamp variable will be set to the empty string ("").
-
-See the :command:`string(TIMESTAMP)` command for documentation of
-the ``<format>`` and ``UTC`` options.
-
-------------------------------------------------------------------------------
-
-::
-
-  file(GENERATE OUTPUT output-file
-       <INPUT input-file|CONTENT content>
-       [CONDITION expression])
-
-Generate an output file for each build configuration supported by the current
-:manual:`CMake Generator <cmake-generators(7)>`.  Evaluate
-:manual:`generator expressions <cmake-generator-expressions(7)>`
-from the input content to produce the output content.  The options are:
-
-``CONDITION <condition>``
-  Generate the output file for a particular configuration only if
-  the condition is true.  The condition must be either ``0`` or ``1``
-  after evaluating generator expressions.
-
-``CONTENT <content>``
-  Use the content given explicitly as input.
-
-``INPUT <input-file>``
-  Use the content from a given file as input.
-  A relative path is treated with respect to the value of
-  :variable:`CMAKE_CURRENT_SOURCE_DIR`.  See policy :policy:`CMP0070`.
-
-``OUTPUT <output-file>``
-  Specify the output file name to generate.  Use generator expressions
-  such as ``$<CONFIG>`` to specify a configuration-specific output file
-  name.  Multiple configurations may generate the same output file only
-  if the generated content is identical.  Otherwise, the ``<output-file>``
-  must evaluate to an unique name for each configuration.
-  A relative path (after evaluating generator expressions) is treated
-  with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
-  See policy :policy:`CMP0070`.
-
-Exactly one ``CONTENT`` or ``INPUT`` option must be given.  A specific
-``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
-Generated files are modified and their timestamp updated on subsequent cmake
-runs only if their content is changed.
-
-Note also that ``file(GENERATE)`` does not create the output file until the
-generation phase. The output file will not yet have been written when the
-``file(GENERATE)`` command returns, it is written only after processing all
-of a project's ``CMakeLists.txt`` files.
-
-------------------------------------------------------------------------------
-
-::
-
-  file(<COPY|INSTALL> <files>... DESTINATION <dir>
-       [FILE_PERMISSIONS <permissions>...]
-       [DIRECTORY_PERMISSIONS <permissions>...]
-       [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
-       [FILES_MATCHING]
-       [[PATTERN <pattern> | REGEX <regex>]
-        [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
-
-The ``COPY`` signature copies files, directories, and symlinks to a
-destination folder.  Relative input paths are evaluated with respect
-to the current source directory, and a relative destination is
-evaluated with respect to the current build directory.  Copying
-preserves input file timestamps, and optimizes out a file if it exists
-at the destination with the same timestamp.  Copying preserves input
-permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
-are given (default is ``USE_SOURCE_PERMISSIONS``).
-
-See the :command:`install(DIRECTORY)` command for documentation of
-permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and
-``EXCLUDE`` options.  Copying directories preserves the structure
-of their content even if options are used to select a subset of
-files.
-
-The ``INSTALL`` signature differs slightly from ``COPY``: it prints
-status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable),
-and ``NO_SOURCE_PERMISSIONS`` is default.
-Installation scripts generated by the :command:`install` command
-use this signature (with some undocumented options for internal use).
+Locking
+^^^^^^^
 
-------------------------------------------------------------------------------
+.. _LOCK:
 
 ::
 

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
@@ -33,11 +59,10 @@ scope.  To propagate the results of these operations upwards, use
   Be careful when counting with negative indices: they do not start from
   0.  -0 is equivalent to 0, the first list element.
 
-Capacity and Element access
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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:
 
 ::
 

Source/cmRST.cxx

@@ -39,6 +39,8 @@ cmRST::cmRST(std::ostream& os, std::string const& docroot)
               "prop_test|prop_tgt|"
               "manual"
               "):`(<*([^`<]|[^` \t]<)*)([ \t]+<[^`]*>)?`")
+  , InlineLink("`(<*([^`<]|[^` \t]<)*)([ \t]+<[^`]*>)?`_")
+  , InlineLiteral("``([^`]*)``")
   , Substitution("(^|[^A-Za-z0-9_])"
                  "((\\|[^| \t\r\n]([^|\r\n]*[^| \t\r\n])?\\|)(__|_|))"
                  "([^A-Za-z0-9_]|$)")
@@ -245,18 +247,62 @@ void cmRST::OutputLine(std::string const& line_in, bool inlineMarkup)
   if (inlineMarkup) {
     std::string line = this->ReplaceSubstitutions(line_in);
     std::string::size_type pos = 0;
-    while (this->CMakeRole.find(line.c_str() + pos)) {
-      this->OS << line.substr(pos, this->CMakeRole.start());
-      std::string text = this->CMakeRole.match(3);
-      // If a command reference has no explicit target and
-      // no explicit "(...)" then add "()" to the text.
-      if (this->CMakeRole.match(2) == "command" &&
-          this->CMakeRole.match(5).empty() &&
-          text.find_first_of("()") == std::string::npos) {
-        text += "()";
+    for (;;) {
+      std::string::size_type* first = nullptr;
+      std::string::size_type role_start = std::string::npos;
+      std::string::size_type link_start = std::string::npos;
+      std::string::size_type lit_start = std::string::npos;
+      if (this->CMakeRole.find(line.c_str() + pos)) {
+        role_start = this->CMakeRole.start();
+        first = &role_start;
+      }
+      if (this->InlineLiteral.find(line.c_str() + pos)) {
+        lit_start = this->InlineLiteral.start();
+        if (!first || lit_start < *first) {
+          first = &lit_start;
+        }
+      }
+      if (this->InlineLink.find(line.c_str() + pos)) {
+        link_start = this->InlineLink.start();
+        if (!first || link_start < *first) {
+          first = &link_start;
+        }
+      }
+      if (first == &role_start) {
+        this->OS << line.substr(pos, role_start);
+        std::string text = this->CMakeRole.match(3);
+        // If a command reference has no explicit target and
+        // no explicit "(...)" then add "()" to the text.
+        if (this->CMakeRole.match(2) == "command" &&
+            this->CMakeRole.match(5).empty() &&
+            text.find_first_of("()") == std::string::npos) {
+          text += "()";
+        }
+        this->OS << "``" << text << "``";
+        pos += this->CMakeRole.end();
+      } else if (first == &lit_start) {
+        this->OS << line.substr(pos, lit_start);
+        std::string text = this->InlineLiteral.match(1);
+        pos += this->InlineLiteral.end();
+        this->OS << "``" << text << "``";
+      } else if (first == &link_start) {
+        this->OS << line.substr(pos, link_start);
+        std::string text = this->InlineLink.match(1);
+        bool escaped = false;
+        for (char c : text) {
+          if (escaped) {
+            escaped = false;
+            this->OS << c;
+          } else if (c == '\\') {
+            escaped = true;
+          } else {
+            this->OS << c;
+          }
+        }
+        pos += this->InlineLink.end();
+      } else {
+        break;
       }
-      this->OS << "``" << text << "``";
-      pos += this->CMakeRole.end();
     }
     this->OS << line.substr(pos) << "\n";
   } else {

Source/cmRST.h

@@ -85,6 +85,8 @@ private:
   cmsys::RegularExpression NoteDirective;
   cmsys::RegularExpression ModuleRST;
   cmsys::RegularExpression CMakeRole;
+  cmsys::RegularExpression InlineLink;
+  cmsys::RegularExpression InlineLiteral;
   cmsys::RegularExpression Substitution;
   cmsys::RegularExpression TocTreeLink;
 

Tests/CMakeLib/testRST.expect

@@ -19,6 +19,10 @@ Variable ``VARIABLE_<PLACEHOLDER>`` with trailing placeholder and target.
 Environment variable ``SOME_ENV_VAR``.
 Environment variable ``some env var`` with space and target.
 Generator ``Some Generator`` with space.
+Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``.
+Inline link Link Text.
+Inline link Link Text <With \-escaped Brackets>.
+Inline literal ``__`` followed by inline link Link Text.
 
 First TOC entry.
 

Tests/CMakeLib/testRST.rst

@@ -26,6 +26,10 @@ Variable :variable:`VARIABLE_<PLACEHOLDER> <target>` with trailing placeholder a
 Environment variable :envvar:`SOME_ENV_VAR`.
 Environment variable :envvar:`some env var <SOME_ENV_VAR>` with space and target.
 Generator :generator:`Some Generator` with space.
+Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``.
+Inline link `Link Text <ExternalDest>`_.
+Inline link `Link Text \<With \\-escaped Brackets\> <ExternalDest>`_.
+Inline literal ``__`` followed by inline link `Link Text <InternalDest_>`_.
 
 .. |not replaced| replace:: not replaced through toctree
 .. |not replaced in literal| replace:: replaced in parsed literal

Utilities/Sphinx/static/cmake.css

@@ -6,3 +6,13 @@
 div.sphinxsidebarwrapper {
   word-wrap: break-word;
 }
+
+/* Make links inside parsed-literal blocks more obvious
+   by using a background color and increased line spacing
+   to make them look boxed.  */
+.literal-block {
+  line-height: 1.4;
+}
+.literal-block a.reference.internal {
+  background-color: #dfdfdf;
+}