From 6e85ad7f8bddf9347fce828bb18940c07dc603c2 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 24 Feb 2023 12:21:39 -0500 Subject: Help/dev: Add per-directive sections in CMake Documentation Guide --- Help/dev/documentation.rst | 95 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 70 insertions(+), 25 deletions(-) diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index db92022..cd9f784 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -168,46 +168,91 @@ documentation: See the `cmake-variables(7)`_ manual and the `set()`_ command. -Documentation objects in the CMake Domain come from two sources. -First, the CMake extension to Sphinx transforms every document named -with the form ``Help//.rst`` to a domain object with -type ````. The object name is extracted from the document title, -which is expected to be of the form:: - - - ------------- - -and to appear at or near the top of the ``.rst`` file before any other -lines starting in a letter, digit, ``<``, or ``$``. If no such title appears -literally in the ``.rst`` file, the object name is the ````. -If a title does appear, it is expected that ```` is equal -to ```` with any ``<`` and ``>`` characters removed, -or in the case of a ``$`` or ``$``, the -``genex-name``. - -Second, the CMake Domain provides directives to define objects inside -other documents: +Documentation objects in the CMake Domain come from two sources: + +1. The CMake extension to Sphinx transforms every document named + with the form ``Help//.rst`` to a domain object with + type ````. The object name is extracted from the document title, + which is expected to be of the form:: + + + ------------- + + and to appear at or near the top of the ``.rst`` file before any other lines + starting in a letter, digit, ``<``, or ``$``. If no such title appears + literally in the ``.rst`` file, the object name is the ````. + If a title does appear, it is expected that ```` is equal + to ```` with any ``<`` and ``>`` characters removed, + or in the case of a ``$`` or ``$``, the + ``genex-name``. + +2. `CMake Domain directives`_ may be used in documents to explicitly define + some object types: + + * `command directive`_ + * `envvar directive`_ + * `genex directive`_ + * `variable directive`_ + + Object types for which no directive is available must be defined using + the document transform above. + +CMake Domain Directives +----------------------- + +The CMake Domain provides the following directives. + +``command`` directive +^^^^^^^^^^^^^^^^^^^^^ + +Document a "command" object: + +.. code-block:: rst + + .. command:: + + This indented block documents . + +The directive requires a single argument, the command name. + +``envvar`` directive +^^^^^^^^^^^^^^^^^^^^ + +Document an "envvar" object: .. code-block:: rst - .. command:: + .. envvar:: - This indented block documents . + This indented block documents . - .. envvar:: +The directive requires a single argument, the environment variable name. - This indented block documents . +``genex`` directive +^^^^^^^^^^^^^^^^^^^ + +Document a "genex" object: + +.. code-block:: rst .. genex:: This indented block documents . +The directive requires a single argument, the generator expression name. + +``variable`` directive +^^^^^^^^^^^^^^^^^^^^^^ + +Document a "variable" object: + +.. code-block:: rst + .. variable:: This indented block documents . -Object types for which no directive is available must be defined using -the first approach above. +The directive requires a single argument, the variable name. .. _`Sphinx Domain`: http://sphinx-doc.org/domains.html .. _`cmake(1)`: https://cmake.org/cmake/help/latest/manual/cmake.1.html -- cgit v0.12 From c09b7604841448b0c949e5c98ea791c9dc9d477e Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 23 Feb 2023 17:22:46 -0500 Subject: Utilities/Sphinx: Drop commented-out code from cmake domain impl Inspired-by: Alex Turbov --- Utilities/Sphinx/cmake.py | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py index 47e4909..e9f0dc5 100644 --- a/Utilities/Sphinx/cmake.py +++ b/Utilities/Sphinx/cmake.py @@ -412,18 +412,7 @@ class CMakeDomain(Domain): 'envvar': CMakeObject, 'genex': CMakeObject, 'variable': CMakeObject, - # Other object types cannot be created except by the CMakeTransform - # 'generator': CMakeObject, - # 'module': CMakeObject, - # 'policy': CMakeObject, - # 'prop_cache': CMakeObject, - # 'prop_dir': CMakeObject, - # 'prop_gbl': CMakeObject, - # 'prop_inst': CMakeObject, - # 'prop_sf': CMakeObject, - # 'prop_test': CMakeObject, - # 'prop_tgt': CMakeObject, - # 'manual': CMakeObject, + # Other `object_types` cannot be created except by the `CMakeTransform` } roles = { 'command': CMakeXRefRole(fix_parens = True, lowercase = True), -- cgit v0.12 From 74e3c1d313616b5faf83ff423c8e8ef3f2010a41 Mon Sep 17 00:00:00 2001 From: Matthew Woehlke Date: Fri, 24 Feb 2023 15:01:14 -0500 Subject: Utilities/Sphinx: Add a directive to document command signatures Add a `signature` directive to offer a CMake version of Sphinx's `function` directive, similar to that found in other domains (py, cpp, etc.). Like others, this takes one or more signatures as arguments and creates dt/dd nodes from the signatures and the directive contents. --- Help/dev/documentation.rst | 95 +++++++++++++++++++++++++++++++++------ Source/cmRST.cxx | 2 +- Tests/CMakeLib/testRST.expect | 8 ++++ Tests/CMakeLib/testRST.rst | 8 ++++ Utilities/Sphinx/cmake.py | 85 +++++++++++++++++++++++++++++++++-- Utilities/Sphinx/static/cmake.css | 23 ++++++++++ 6 files changed, 204 insertions(+), 17 deletions(-) diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index cd9f784..a340739 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -241,6 +241,69 @@ Document a "genex" object: The directive requires a single argument, the generator expression name. +``signature`` directive +^^^^^^^^^^^^^^^^^^^^^^^ + +Document `CMake Command Signatures `_ +within a ``Help/command/.rst`` document. + +.. code-block:: rst + + .. signature:: () + + This indented block documents one or more signatures of a CMake command. + +The ``signature`` directive requires one argument, the signature summary: + +* One or more signatures must immediately follow the ``::``. + The first signature may optionally be placed on the same line. + A blank line following the ``signature`` directive will result in a + documentation generation error: ``1 argument(s) required, 0 supplied``. + +* Signatures may be split across multiple lines, but the final ``)`` of each + signature must be the last character on its line. + +* Blank lines between signatures are not allowed. (Content after a blank line + is treated as part of the description.) + +* Whitespace in signatures is not preserved. To document a complex signature, + abbreviate it in the ``signature`` directive argument and specify the full + signature in a ``code-block`` in the description. + +The ``signature`` directive generates a document-local hyperlink target +for each signature: + +* Default target names are automatically extracted from leading "keyword" + arguments in the signatures, where a keyword is any sequence of + non-space starting with a letter. For example, the signature + ``string(REGEX REPLACE ...)`` generates the target + ``REGEX REPLACE``, similar to ``.. _`REGEX REPLACE`:``. + +* Custom target names may be specified using a ``:target:`` option. + For example: + + .. code-block:: rst + + .. signature:: + cmake_path(GET ROOT_NAME ) + cmake_path(GET ROOT_PATH ) + :target: + GET ROOT_NAME + GET ROOT_PATH + + Provide a custom target name for each signature, one per line. + The first target may optionally be placed on the same line as ``:target:``. + +* If a target name is already in use earlier in the document, no hyperlink + target will be generated. + +* The targets may be referenced from within the same document using + ```REF`_`` or ```TEXT `_`` syntax. Like reStructuredText section + headers, the targets do not work with Sphinx ``:ref:`` syntax. + +The directive treats its content as the documentation of the signature(s). +Indent the signature documentation accordingly. + ``variable`` directive ^^^^^^^^^^^^^^^^^^^^^^ @@ -374,11 +437,11 @@ paragraph. Style: CMake Command Signatures ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Command signatures should be marked up as plain literal blocks, not as -cmake ``code-blocks``. - -Signatures are separated from preceding content by a section header. -That is, use: +A ``Help/command/.rst`` document defines one ``command`` +object in the `CMake Domain`_, but some commands have multiple signatures. +Use the CMake Domain's `signature directive`_ to document each signature. +Separate signatures from preceding content by a section header. +For example: .. code-block:: rst @@ -387,17 +450,23 @@ That is, use: Normal Libraries ^^^^^^^^^^^^^^^^ - :: - + .. signature:: add_library( ...) - This signature is used for ... + This signature is used for ... + +Use the following conventions in command signature documentation: + +* Use an angle-bracket ```` for arguments to be specified + by the caller. Refer to them in prose using + `inline literal `_ syntax. + +* Wrap optional parts with square brackets. + +* Mark repeatable parts with a trailing ellipsis (``...``). -Signatures of commands should wrap optional parts with square brackets, -and should mark list of optional arguments with an ellipsis (``...``). -Elements of the signature which are specified by the user should be -specified with angle brackets, and may be referred to in prose using -``inline-literal`` syntax. +The ``signature`` directive may be used multiple times for different +signatures of the same command. Style: Boolean Constants ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Source/cmRST.cxx b/Source/cmRST.cxx index fa9d4cc..71b77e0 100644 --- a/Source/cmRST.cxx +++ b/Source/cmRST.cxx @@ -20,7 +20,7 @@ cmRST::cmRST(std::ostream& os, std::string docroot) : OS(os) , DocRoot(std::move(docroot)) , CMakeDirective("^.. (cmake:)?(" - "command|envvar|genex|variable" + "command|envvar|genex|signature|variable" ")::[ \t]+([^ \t\n]+)$") , CMakeModuleDirective("^.. cmake-module::[ \t]+([^ \t\n]+)$") , ParsedLiteralDirective("^.. parsed-literal::[ \t]*(.*)$") diff --git a/Tests/CMakeLib/testRST.expect b/Tests/CMakeLib/testRST.expect index 5e3cdb1..076562a 100644 --- a/Tests/CMakeLib/testRST.expect +++ b/Tests/CMakeLib/testRST.expect @@ -70,6 +70,14 @@ Bracket Comment Content Generator expression $ description. +.. cmake:signature:: some_command(SOME_SIGNATURE) + + Command some_command SOME_SIGNATURE description. + +.. signature:: other_command(OTHER_SIGNATURE) + + Command other_command OTHER_SIGNATURE description. + .. cmake:variable:: some_var Variable some_var description. diff --git a/Tests/CMakeLib/testRST.rst b/Tests/CMakeLib/testRST.rst index 4139801..43b08da 100644 --- a/Tests/CMakeLib/testRST.rst +++ b/Tests/CMakeLib/testRST.rst @@ -73,6 +73,14 @@ Inline literal ``__`` followed by inline link `Link Text `_. Generator expression $ description. +.. cmake:signature:: some_command(SOME_SIGNATURE) + + Command some_command SOME_SIGNATURE description. + +.. signature:: other_command(OTHER_SIGNATURE) + + Command other_command OTHER_SIGNATURE description. + .. cmake:variable:: some_var Variable some_var description. diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py index e9f0dc5..9043709 100644 --- a/Utilities/Sphinx/cmake.py +++ b/Utilities/Sphinx/cmake.py @@ -16,6 +16,9 @@ from pygments.lexers import CMakeLexer from pygments.token import Name, Operator, Punctuation, String, Text, Comment, Generic, Whitespace, Number from pygments.lexer import bygroups +# RE to split multiple command signatures +sig_end_re = re.compile(r'(?<=[)])\n') + # Notes on regular expressions below: # - [\.\+-] are needed for string constants like gtk+-2.0 # - Unix paths are recognized by '/'; support for Windows paths may be added if needed @@ -57,14 +60,16 @@ CMakeLexer.tokens["root"] = [ # (r'[^<>\])\}\|$"# \t\n]+', Name.Exception), # fallback, for debugging only ] +from docutils.utils.code_analyzer import Lexer, LexerError from docutils.parsers.rst import Directive, directives from docutils.transforms import Transform from docutils import io, nodes -from sphinx.directives import ObjectDescription +from sphinx.directives import ObjectDescription, nl_escape_re from sphinx.domains import Domain, ObjType from sphinx.roles import XRefRole from sphinx.util.nodes import make_refnode +from sphinx.util import ws_re from sphinx import addnodes sphinx_before_1_4 = False @@ -286,9 +291,9 @@ class CMakeObject(ObjectDescription): def add_target_and_index(self, name, sig, signode): if self.objtype == 'command': - targetname = name.lower() + targetname = name.lower() else: - targetname = name + targetname = name targetid = '%s:%s' % (self.objtype, targetname) if targetid not in self.state.document.ids: signode['names'].append(targetid) @@ -302,6 +307,79 @@ class CMakeObject(ObjectDescription): if make_index_entry: self.indexnode['entries'].append(make_index_entry(name, targetid)) +class CMakeSignatureObject(CMakeObject): + object_type = 'signature' + + option_spec = { + 'target': directives.unchanged, + } + + def get_signatures(self): + content = nl_escape_re.sub('', self.arguments[0]) + lines = sig_end_re.split(content) + return [ws_re.sub(' ', line.strip()) for line in lines] + + def handle_signature(self, sig, signode): + language = 'cmake' + classes = ['code', 'cmake', 'highlight'] + + node = addnodes.desc_name(sig, '', classes=classes) + + try: + tokens = Lexer(sig, language, 'short') + except LexerError as error: + if self.state.document.settings.report_level > 2: + # Silently insert without syntax highlighting. + tokens = Lexer(sig, language, 'none') + else: + raise self.warning(error) + + for classes, value in tokens: + if classes: + node += nodes.inline(value, value, classes=classes) + else: + node += nodes.Text(value) + + signode.clear() + signode += node + + return sig + + def __init__(self, *args, **kwargs): + self.targetnames = {} + super().__init__(*args, **kwargs) + + def add_target_and_index(self, name, sig, signode): + if name in self.targetnames: + targetname = self.targetnames[name].lower() + else: + def extract_keywords(params): + for p in params: + if p[0].isalpha(): + yield p + else: + return + + keywords = extract_keywords(name.split('(')[1].split()) + targetname = ' '.join(keywords).lower() + targetid = nodes.make_id(targetname) + + if targetid not in self.state.document.ids: + signode['names'].append(targetname) + signode['ids'].append(targetid) + signode['first'] = (not self.names) + self.state.document.note_explicit_target(signode) + + def run(self): + targets = self.options.get('target') + if targets is not None: + signatures = self.get_signatures() + targets = [t.strip() for t in targets.split('\n')] + for signature, target in zip(signatures, targets): + self.targetnames[signature] = target + + return super().run() + class CMakeXRefRole(XRefRole): # See sphinx.util.nodes.explicit_title_re; \x00 escapes '<'. @@ -411,6 +489,7 @@ class CMakeDomain(Domain): 'command': CMakeObject, 'envvar': CMakeObject, 'genex': CMakeObject, + 'signature': CMakeSignatureObject, 'variable': CMakeObject, # Other `object_types` cannot be created except by the `CMakeTransform` } diff --git a/Utilities/Sphinx/static/cmake.css b/Utilities/Sphinx/static/cmake.css index 324cd92..dd0dd02 100644 --- a/Utilities/Sphinx/static/cmake.css +++ b/Utilities/Sphinx/static/cmake.css @@ -17,6 +17,29 @@ div.sphinxsidebarwrapper { background-color: #dfdfdf; } +/* Apply 
 style (from classic.css) to signature directive argument. */
+.signature .sig {
+  padding: 5px;
+  background-color: #eeeeee;
+  color: #333333;
+  line-height: 120%;
+  border: 1px solid #ac9;
+  border-left: none;
+  border-right: none;
+}
+
+/* Add additional styling to signature directive argument. */
+.signature .sig {
+  margin-bottom: 5px;
+  padding-left: calc(5px + 3em);
+  text-indent: -3em;
+  font-family: monospace;
+}
+
+.signature .sig .code.sig-name {
+  font-weight: normal;
+}
+
 /* Remove unwanted margin in case list item contains a div-wrapping
    directive like `.. versionadded` or `.. deprecated`. */
 dd > :first-child > p {
-- 
cgit v0.12


From cd33f461a668268c102075c5f1194c22f95c44a0 Mon Sep 17 00:00:00 2001
From: Matthew Woehlke 
Date: Mon, 27 Feb 2023 11:08:32 -0500
Subject: Help: Use signature directive for cmake_language command

---
 Help/command/cmake_language.rst | 319 +++++++++++++++++++---------------------
 1 file changed, 153 insertions(+), 166 deletions(-)

diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst
index 8801a9f..707568c 100644
--- a/Help/command/cmake_language.rst
+++ b/Help/command/cmake_language.rst
@@ -27,163 +27,155 @@ those created via the :command:`macro` or :command:`function` commands.
 Calling Commands
 ^^^^^^^^^^^^^^^^
 
-.. _CALL:
-
-.. code-block:: cmake
-
+.. signature::
   cmake_language(CALL  [...])
 
-Calls the named ```` with the given arguments (if any).
-For example, the code:
+  Calls the named ```` with the given arguments (if any).
+  For example, the code:
 
-.. code-block:: cmake
+  .. code-block:: cmake
 
-  set(message_command "message")
-  cmake_language(CALL ${message_command} STATUS "Hello World!")
+    set(message_command "message")
+    cmake_language(CALL ${message_command} STATUS "Hello World!")
 
-is equivalent to
+  is equivalent to
 
-.. code-block:: cmake
+  .. code-block:: cmake
 
-  message(STATUS "Hello World!")
+    message(STATUS "Hello World!")
 
-.. note::
-  To ensure consistency of the code, the following commands are not allowed:
+  .. note::
+    To ensure consistency of the code, the following commands are not allowed:
 
-  * ``if`` / ``elseif`` / ``else`` / ``endif``
-  * ``block`` / ``endblock``
-  * ``while`` / ``endwhile``
-  * ``foreach`` / ``endforeach``
-  * ``function`` / ``endfunction``
-  * ``macro`` / ``endmacro``
+    * ``if`` / ``elseif`` / ``else`` / ``endif``
+    * ``block`` / ``endblock``
+    * ``while`` / ``endwhile``
+    * ``foreach`` / ``endforeach``
+    * ``function`` / ``endfunction``
+    * ``macro`` / ``endmacro``
 
 Evaluating Code
 ^^^^^^^^^^^^^^^
 
-.. _EVAL:
-
-.. code-block:: cmake
-
+.. signature::
   cmake_language(EVAL CODE ...)
+  :target: EVAL
 
-Evaluates the ``...`` as CMake code.
+  Evaluates the ``...`` as CMake code.
 
-For example, the code:
+  For example, the code:
 
-.. code-block:: cmake
+  .. code-block:: cmake
 
-  set(A TRUE)
-  set(B TRUE)
-  set(C TRUE)
-  set(condition "(A AND B) OR C")
+    set(A TRUE)
+    set(B TRUE)
+    set(C TRUE)
+    set(condition "(A AND B) OR C")
 
-  cmake_language(EVAL CODE "
-    if (${condition})
-      message(STATUS TRUE)
-    else()
-      message(STATUS FALSE)
-    endif()"
-  )
+    cmake_language(EVAL CODE "
+      if (${condition})
+        message(STATUS TRUE)
+      else()
+        message(STATUS FALSE)
+      endif()"
+    )
 
-is equivalent to
+  is equivalent to
 
-.. code-block:: cmake
+  .. code-block:: cmake
 
-  set(A TRUE)
-  set(B TRUE)
-  set(C TRUE)
-  set(condition "(A AND B) OR C")
-
-  file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
-    if (${condition})
-      message(STATUS TRUE)
-    else()
-      message(STATUS FALSE)
-    endif()"
-  )
+    set(A TRUE)
+    set(B TRUE)
+    set(C TRUE)
+    set(condition "(A AND B) OR C")
 
-  include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
+    file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
+      if (${condition})
+        message(STATUS TRUE)
+      else()
+        message(STATUS FALSE)
+      endif()"
+    )
+
+    include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
 
 Deferring Calls
 ^^^^^^^^^^^^^^^
 
 .. versionadded:: 3.19
 
-.. _DEFER:
-
-.. code-block:: cmake
-
+.. signature::
   cmake_language(DEFER ... CALL  [...])
 
-Schedules a call to the named ```` with the given arguments (if any)
-to occur at a later time.  By default, deferred calls are executed as if
-written at the end of the current directory's ``CMakeLists.txt`` file,
-except that they run even after a :command:`return` call.  Variable
-references in arguments are evaluated at the time the deferred call is
-executed.
+  Schedules a call to the named ```` with the given arguments (if any)
+  to occur at a later time.  By default, deferred calls are executed as if
+  written at the end of the current directory's ``CMakeLists.txt`` file,
+  except that they run even after a :command:`return` call.  Variable
+  references in arguments are evaluated at the time the deferred call is
+  executed.
 
-The options are:
+  The options are:
 
-``DIRECTORY ``
-  Schedule the call for the end of the given directory instead of the
-  current directory.  The ```` may reference either a source
-  directory or its corresponding binary directory.  Relative paths are
-  treated as relative to the current source directory.
+  ``DIRECTORY ``
+    Schedule the call for the end of the given directory instead of the
+    current directory.  The ```` may reference either a source
+    directory or its corresponding binary directory.  Relative paths are
+    treated as relative to the current source directory.
 
-  The given directory must be known to CMake, being either the top-level
-  directory or one added by :command:`add_subdirectory`.  Furthermore,
-  the given directory must not yet be finished processing.  This means
-  it can be the current directory or one of its ancestors.
+    The given directory must be known to CMake, being either the top-level
+    directory or one added by :command:`add_subdirectory`.  Furthermore,
+    the given directory must not yet be finished processing.  This means
+    it can be the current directory or one of its ancestors.
 
-``ID ``
-  Specify an identification for the deferred call.
-  The ```` may not be empty and may not begin with a capital letter ``A-Z``.
-  The ```` may begin with an underscore (``_``) only if it was generated
-  automatically by an earlier call that used ``ID_VAR`` to get the id.
+  ``ID ``
+    Specify an identification for the deferred call.
+    The ```` may not be empty and may not begin with a capital letter ``A-Z``.
+    The ```` may begin with an underscore (``_``) only if it was generated
+    automatically by an earlier call that used ``ID_VAR`` to get the id.
 
-``ID_VAR ``
-  Specify a variable in which to store the identification for the
-  deferred call.  If ``ID `` is not given, a new identification
-  will be generated and the generated id will start with an underscore (``_``).
+  ``ID_VAR ``
+    Specify a variable in which to store the identification for the
+    deferred call.  If ``ID `` is not given, a new identification
+    will be generated and the generated id will start with an underscore (``_``).
 
-The currently scheduled list of deferred calls may be retrieved:
+  The currently scheduled list of deferred calls may be retrieved:
 
-.. code-block:: cmake
+  .. code-block:: cmake
 
-  cmake_language(DEFER [DIRECTORY ] GET_CALL_IDS )
+    cmake_language(DEFER [DIRECTORY ] GET_CALL_IDS )
 
-This will store in ```` a :ref:`semicolon-separated list ` of deferred call ids.  The ids are for the directory scope in which
-the calls have been deferred to (i.e. where they will be executed), which can
-be different to the scope in which they were created.  The ``DIRECTORY``
-option can be used to specify the scope for which to retrieve the call ids.
-If that option is not given, the call ids for the current directory scope will
-be returned.
+  This will store in ```` a :ref:`semicolon-separated list ` of deferred call ids.  The ids are for the directory scope in which
+  the calls have been deferred to (i.e. where they will be executed), which can
+  be different to the scope in which they were created.  The ``DIRECTORY``
+  option can be used to specify the scope for which to retrieve the call ids.
+  If that option is not given, the call ids for the current directory scope
+  will be returned.
 
-Details of a specific call may be retrieved from its id:
+  Details of a specific call may be retrieved from its id:
 
-.. code-block:: cmake
+  .. code-block:: cmake
 
-  cmake_language(DEFER [DIRECTORY ] GET_CALL  )
+    cmake_language(DEFER [DIRECTORY ] GET_CALL  )
 
-This will store in ```` a :ref:`semicolon-separated list ` in which the first element is the name of the command to be
-called, and the remaining elements are its unevaluated arguments (any
-contained ``;`` characters are included literally and cannot be distinguished
-from multiple arguments).  If multiple calls are scheduled with the same id,
-this retrieves the first one.  If no call is scheduled with the given id in
-the specified ``DIRECTORY`` scope (or the current directory scope if no
-``DIRECTORY`` option is given), this stores an empty string in the variable.
+  This will store in ```` a :ref:`semicolon-separated list ` in which the first element is the name of the command to be
+  called, and the remaining elements are its unevaluated arguments (any
+  contained ``;`` characters are included literally and cannot be distinguished
+  from multiple arguments).  If multiple calls are scheduled with the same id,
+  this retrieves the first one.  If no call is scheduled with the given id in
+  the specified ``DIRECTORY`` scope (or the current directory scope if no
+  ``DIRECTORY`` option is given), this stores an empty string in the variable.
 
-Deferred calls may be canceled by their id:
+  Deferred calls may be canceled by their id:
 
-.. code-block:: cmake
+  .. code-block:: cmake
 
-  cmake_language(DEFER [DIRECTORY ] CANCEL_CALL ...)
+    cmake_language(DEFER [DIRECTORY ] CANCEL_CALL ...)
 
-This cancels all deferred calls matching any of the given ids in the specified
-``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option
-is given).  Unknown ids are silently ignored.
+  This cancels all deferred calls matching any of the given ids in the specified
+  ``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option
+  is given).  Unknown ids are silently ignored.
 
 Deferred Call Examples
 """"""""""""""""""""""
@@ -229,8 +221,6 @@ also prints::
   Deferred Message 1
   Deferred Message 2
 
-
-.. _SET_DEPENDENCY_PROVIDER:
 .. _dependency_providers:
 
 Dependency Providers
@@ -241,51 +231,50 @@ Dependency Providers
 .. note:: A high-level introduction to this feature can be found in the
           :ref:`Using Dependencies Guide `.
 
-.. code-block:: cmake
-
+.. signature::
   cmake_language(SET_DEPENDENCY_PROVIDER 
                  SUPPORTED_METHODS ...)
 
-When a call is made to :command:`find_package` or
-:command:`FetchContent_MakeAvailable`, the call may be forwarded to a
-dependency provider which then has the opportunity to fulfill the request.
-If the request is for one of the ```` specified when the provider
-was set, CMake calls the provider's ```` with a set of
-method-specific arguments.  If the provider does not fulfill the request,
-or if the provider doesn't support the request's method, or no provider
-is set, the built-in :command:`find_package` or
-:command:`FetchContent_MakeAvailable` implementation is used to fulfill
-the request in the usual way.
-
-One or more of the following values can be specified for the ````
-when setting the provider:
-
-``FIND_PACKAGE``
-  The provider command accepts :command:`find_package` requests.
-
-``FETCHCONTENT_MAKEAVAILABLE_SERIAL``
-  The provider command accepts :command:`FetchContent_MakeAvailable`
-  requests.  It expects each dependency to be fed to the provider command
-  one at a time, not the whole list in one go.
-
-Only one provider can be set at any point in time.  If a provider is already
-set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new
-provider replaces the previously set one.  The specified ```` must
-already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called.
-As a special case, providing an empty string for the ```` and no
-```` will discard any previously set provider.
-
-The dependency provider can only be set while processing one of the files
-specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable.
-Thus, dependency providers can only be set as part of the first call to
-:command:`project`.  Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)``
-outside of that context will result in an error.
-
-.. note::
-  The choice of dependency provider should always be under the user's control.
-  As a convenience, a project may choose to provide a file that users can
-  list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but
-  the use of such a file should always be the user's choice.
+  When a call is made to :command:`find_package` or
+  :command:`FetchContent_MakeAvailable`, the call may be forwarded to a
+  dependency provider which then has the opportunity to fulfill the request.
+  If the request is for one of the ```` specified when the provider
+  was set, CMake calls the provider's ```` with a set of
+  method-specific arguments.  If the provider does not fulfill the request,
+  or if the provider doesn't support the request's method, or no provider
+  is set, the built-in :command:`find_package` or
+  :command:`FetchContent_MakeAvailable` implementation is used to fulfill
+  the request in the usual way.
+
+  One or more of the following values can be specified for the ````
+  when setting the provider:
+
+  ``FIND_PACKAGE``
+    The provider command accepts :command:`find_package` requests.
+
+  ``FETCHCONTENT_MAKEAVAILABLE_SERIAL``
+    The provider command accepts :command:`FetchContent_MakeAvailable`
+    requests.  It expects each dependency to be fed to the provider command
+    one at a time, not the whole list in one go.
+
+  Only one provider can be set at any point in time.  If a provider is already
+  set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new
+  provider replaces the previously set one.  The specified ```` must
+  already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called.
+  As a special case, providing an empty string for the ```` and no
+  ```` will discard any previously set provider.
+
+  The dependency provider can only be set while processing one of the files
+  specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable.
+  Thus, dependency providers can only be set as part of the first call to
+  :command:`project`.  Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)``
+  outside of that context will result in an error.
+
+  .. note::
+    The choice of dependency provider should always be under the user's control.
+    As a convenience, a project may choose to provide a file that users can
+    list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but
+    the use of such a file should always be the user's choice.
 
 Provider commands
 """""""""""""""""
@@ -499,23 +488,21 @@ Getting current message log level
 
 .. versionadded:: 3.25
 
-.. _GET_MESSAGE_LOG_LEVEL:
 .. _query_message_log_level:
 
-.. code-block:: cmake
-
+.. signature::
   cmake_language(GET_MESSAGE_LOG_LEVEL )
 
-Writes the current :command:`message` logging level
-into the given ````.
+  Writes the current :command:`message` logging level
+  into the given ````.
 
-See :command:`message` for the possible logging levels.
+  See :command:`message` for the possible logging levels.
 
-The current message logging level can be set either using the
-:option:`--log-level `
-command line option of the :manual:`cmake(1)` program or using
-the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable.
+  The current message logging level can be set either using the
+  :option:`--log-level `
+  command line option of the :manual:`cmake(1)` program or using
+  the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable.
 
-If both the command line option and the variable are set, the command line
-option takes precedence. If neither are set, the default logging level
-is returned.
+  If both the command line option and the variable are set, the command line
+  option takes precedence. If neither are set, the default logging level
+  is returned.
-- 
cgit v0.12


From 533ebb072bb90bdba296aac79114a1ed0840759f Mon Sep 17 00:00:00 2001
From: Matthew Woehlke 
Date: Fri, 24 Feb 2023 16:25:16 -0500
Subject: Help: Use signature directive for string command

---
 Help/command/string.rst | 586 +++++++++++++++++++++---------------------------
 1 file changed, 256 insertions(+), 330 deletions(-)

diff --git a/Help/command/string.rst b/Help/command/string.rst
index c24b9bc..b47fa09 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -45,16 +45,16 @@ Synopsis
 
   `JSON`_
     string(JSON  [ERROR_VARIABLE ]
-           {:ref:`GET ` | :ref:`TYPE ` | :ref:`LENGTH ` | :ref:`REMOVE `}
+           {`GET `_ | `TYPE `_ | `LENGTH `_ | `REMOVE `_}
              [ ...])
     string(JSON  [ERROR_VARIABLE ]
-           :ref:`MEMBER ` 
+           `MEMBER `_ 
            [ ...] )
     string(JSON  [ERROR_VARIABLE ]
-           :ref:`SET ` 
+           `SET `_ 
             [ ...] )
     string(JSON  [ERROR_VARIABLE ]
-           :ref:`EQUAL `  )
+           `EQUAL `_  )
 
 Search and Replace
 ^^^^^^^^^^^^^^^^^^
@@ -62,75 +62,60 @@ Search and Replace
 Search and Replace With Plain Strings
 """""""""""""""""""""""""""""""""""""
 
-.. _FIND:
-
-.. code-block:: cmake
-
+.. signature::
   string(FIND    [REVERSE])
 
-Return the position where the given ```` was found in
-the supplied ````.  If the ``REVERSE`` flag was used, the command will
-search for the position of the last occurrence of the specified
-````.  If the ```` is not found, a position of -1 is
-returned.
-
-The ``string(FIND)`` subcommand treats all strings as ASCII-only characters.
-The index stored in ```` will also be counted in bytes,
-so strings containing multi-byte characters may lead to unexpected results.
+  Return the position where the given ```` was found in
+  the supplied ````.  If the ``REVERSE`` flag was used, the command
+  will search for the position of the last occurrence of the specified
+  ````.  If the ```` is not found, a position of -1 is
+  returned.
 
-.. _REPLACE:
-
-.. code-block:: cmake
+  The ``string(FIND)`` subcommand treats all strings as ASCII-only characters.
+  The index stored in ```` will also be counted in bytes,
+  so strings containing multi-byte characters may lead to unexpected results.
 
+.. signature::
   string(REPLACE 
           
           [...])
 
-Replace all occurrences of ```` in the ````
-with ```` and store the result in the ````.
+  Replace all occurrences of ```` in the ````
+  with ```` and store the result in the ````.
 
 Search and Replace With Regular Expressions
 """""""""""""""""""""""""""""""""""""""""""
 
-.. _`REGEX MATCH`:
-
-.. code-block:: cmake
-
+.. signature::
   string(REGEX MATCH 
            [...])
 
-Match the ```` once and store the match in the
-````.
-All ```` arguments are concatenated before matching.
-Regular expressions are specified in the subsection just below.
-
-.. _`REGEX MATCHALL`:
-
-.. code-block:: cmake
+  Match the ```` once and store the match in the
+  ````.
+  All ```` arguments are concatenated before matching.
+  Regular expressions are specified in the subsection just below.
 
+.. signature::
   string(REGEX MATCHALL 
            [...])
 
-Match the ```` as many times as possible and store the
-matches in the ```` as a list.
-All ```` arguments are concatenated before matching.
-
-.. _`REGEX REPLACE`:
-
-.. code-block:: cmake
+  Match the ```` as many times as possible and store the
+  matches in the ```` as a list.
+  All ```` arguments are concatenated before matching.
 
+.. signature::
   string(REGEX REPLACE 
           
           [...])
 
-Match the ```` as many times as possible and substitute
-the ```` for the match in the output.
-All ```` arguments are concatenated before matching.
+  Match the ```` as many times as possible and substitute
+  the ```` for the match in the output.
+  All ```` arguments are concatenated before matching.
 
-The ```` 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.
+  The ```` 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`:
 
@@ -201,130 +186,100 @@ newlines, and backslashes (respectively) to pass in a regex.  For example:
 Manipulation
 ^^^^^^^^^^^^
 
-.. _APPEND:
-
-.. code-block:: cmake
-
+.. signature::
   string(APPEND  [...])
 
-.. versionadded:: 3.4
-
-Append all the ```` arguments to the string.
+  .. versionadded:: 3.4
 
-.. _PREPEND:
-
-.. code-block:: cmake
+  Append all the ```` arguments to the string.
 
+.. signature::
   string(PREPEND  [...])
 
-.. versionadded:: 3.10
-
-Prepend all the ```` arguments to the string.
-
-.. _CONCAT:
+  .. versionadded:: 3.10
 
-.. code-block:: cmake
+  Prepend all the ```` arguments to the string.
 
+.. signature::
   string(CONCAT  [...])
 
-Concatenate all the ```` arguments together and store
-the result in the named ````.
-
-.. _JOIN:
-
-.. code-block:: cmake
+  Concatenate all the ```` arguments together and store
+  the result in the named ````.
 
+.. signature::
   string(JOIN   [...])
 
-.. versionadded:: 3.12
-
-Join all the ```` arguments together using the ````
-string and store the result in the named ````.
-
-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.
+  .. versionadded:: 3.12
 
-.. _TOLOWER:
+  Join all the ```` arguments together using the ````
+  string and store the result in the named ````.
 
-.. code-block:: cmake
+  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.
 
+.. signature::
   string(TOLOWER  )
 
-Convert ```` to lower characters.
-
-.. _TOUPPER:
-
-.. code-block:: cmake
+  Convert ```` to lower characters.
 
+.. signature::
   string(TOUPPER  )
 
-Convert ```` to upper characters.
-
-.. _LENGTH:
-
-.. code-block:: cmake
+  Convert ```` to upper characters.
 
+.. signature::
   string(LENGTH  )
 
-Store in an ```` a given string's length in bytes.
-Note that this means if ```` contains multi-byte characters, the
-result stored in ```` will *not* be the number of characters.
-
-.. _SUBSTRING:
-
-.. code-block:: cmake
+  Store in an ```` a given string's length in bytes.
+  Note that this means if ```` contains multi-byte characters,
+  the result stored in ```` will *not* be
+  the number of characters.
 
+.. signature::
   string(SUBSTRING    )
 
-Store in an ```` a substring of a given ````.  If
-```` is ``-1`` the remainder of the string starting at ````
-will be returned.
-
-.. versionchanged:: 3.2
-  If ```` is shorter than ```` then the end of the string
-  is used instead.  Previous versions of CMake reported an error in this case.
-
-Both ```` and ```` are counted in bytes, so care must
-be exercised if ```` could contain multi-byte characters.
+  Store in an ```` a substring of a given ````.  If
+  ```` is ``-1`` the remainder of the string starting at ````
+  will be returned.
 
-.. _STRIP:
+  .. versionchanged:: 3.2
+    If ```` is shorter than ````
+    then the end of the string is used instead.
+    Previous versions of CMake reported an error in this case.
 
-.. code-block:: cmake
+  Both ```` and ```` are counted in bytes, so care must
+  be exercised if ```` could contain multi-byte characters.
 
+.. signature::
   string(STRIP  )
 
-Store in an ```` a substring of a given ```` with
-leading and trailing spaces removed.
-
-.. _GENEX_STRIP:
-
-.. code-block:: cmake
+  Store in an ```` a substring of a given ````
+  with leading and trailing spaces removed.
 
+.. signature::
   string(GENEX_STRIP  )
 
-.. versionadded:: 3.1
-
-Strip any :manual:`generator expressions `
-from the input ```` and store the result in the ````.
-
-.. _REPEAT:
+  .. versionadded:: 3.1
 
-.. code-block:: cmake
+  Strip any :manual:`generator expressions `
+  from the input ```` and store the result
+  in the ````.
 
+.. signature::
   string(REPEAT   )
 
-.. versionadded:: 3.15
+  .. versionadded:: 3.15
 
-Produce the output string as the input ```` repeated ```` times.
+  Produce the output string as the input ````
+  repeated ```` times.
 
 Comparison
 ^^^^^^^^^^
 
 .. _COMPARE:
 
-.. code-block:: cmake
-
+.. signature::
   string(COMPARE LESS   )
   string(COMPARE GREATER   )
   string(COMPARE EQUAL   )
@@ -332,240 +287,217 @@ Comparison
   string(COMPARE LESS_EQUAL   )
   string(COMPARE GREATER_EQUAL   )
 
-Compare the strings and store true or false in the ````.
+  Compare the strings and store true or false in the ````.
 
-.. versionadded:: 3.7
-  Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options.
+  .. versionadded:: 3.7
+    Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options.
 
 .. _`Supported Hash Algorithms`:
 
 Hashing
 ^^^^^^^
 
-.. _`HASH`:
-
-.. code-block:: cmake
-
+.. signature::
   string(  )
+  :target: HASH
+
+  Compute a cryptographic hash of the ```` string.
+  The supported ```` algorithm names are:
+
+  ``MD5``
+    Message-Digest Algorithm 5, RFC 1321.
+  ``SHA1``
+    US Secure Hash Algorithm 1, RFC 3174.
+  ``SHA224``
+    US Secure Hash Algorithms, RFC 4634.
+  ``SHA256``
+    US Secure Hash Algorithms, RFC 4634.
+  ``SHA384``
+    US Secure Hash Algorithms, RFC 4634.
+  ``SHA512``
+    US Secure Hash Algorithms, RFC 4634.
+  ``SHA3_224``
+    Keccak SHA-3.
+  ``SHA3_256``
+    Keccak SHA-3.
+  ``SHA3_384``
+    Keccak SHA-3.
+  ``SHA3_512``
+    Keccak SHA-3.
 
-Compute a cryptographic hash of the ```` string.
-The supported ```` algorithm names are:
-
-``MD5``
-  Message-Digest Algorithm 5, RFC 1321.
-``SHA1``
-  US Secure Hash Algorithm 1, RFC 3174.
-``SHA224``
-  US Secure Hash Algorithms, RFC 4634.
-``SHA256``
-  US Secure Hash Algorithms, RFC 4634.
-``SHA384``
-  US Secure Hash Algorithms, RFC 4634.
-``SHA512``
-  US Secure Hash Algorithms, RFC 4634.
-``SHA3_224``
-  Keccak SHA-3.
-``SHA3_256``
-  Keccak SHA-3.
-``SHA3_384``
-  Keccak SHA-3.
-``SHA3_512``
-  Keccak SHA-3.
-
-.. versionadded:: 3.8
-  Added the ``SHA3_*`` hash algorithms.
+  .. versionadded:: 3.8
+    Added the ``SHA3_*`` hash algorithms.
 
 Generation
 ^^^^^^^^^^
 
-.. _ASCII:
-
-.. code-block:: cmake
-
+.. signature::
   string(ASCII  [ ...] )
 
-Convert all numbers into corresponding ASCII characters.
-
-.. _HEX:
-
-.. code-block:: cmake
+  Convert all numbers into corresponding ASCII characters.
 
+.. signature::
   string(HEX  )
 
-.. versionadded:: 3.18
-
-Convert each byte in the input ```` to its hexadecimal representation
-and store the concatenated hex digits in the ````. Letters in
-the output (``a`` through ``f``) are in lowercase.
+  .. versionadded:: 3.18
 
-.. _CONFIGURE:
-
-.. code-block:: cmake
+  Convert each byte in the input ```` to its hexadecimal representation
+  and store the concatenated hex digits in the ````.
+  Letters in the output (``a`` through ``f``) are in lowercase.
 
+.. signature::
   string(CONFIGURE  
          [@ONLY] [ESCAPE_QUOTES])
 
-Transform a ```` like :command:`configure_file` transforms a file.
-
-.. _MAKE_C_IDENTIFIER:
-
-.. code-block:: cmake
+  Transform a ```` like :command:`configure_file` transforms a file.
 
+.. signature::
   string(MAKE_C_IDENTIFIER  )
 
-Convert each non-alphanumeric character in the input ```` to an
-underscore and store the result in the ````.  If the first
-character of the ```` is a digit, an underscore will also be prepended
-to the result.
-
-.. _RANDOM:
-
-.. code-block:: cmake
+  Convert each non-alphanumeric character in the input ```` to an
+  underscore and store the result in the ````.  If the first
+  character of the ```` is a digit, an underscore will also be
+  prepended to the result.
 
+.. signature::
   string(RANDOM [LENGTH ] [ALPHABET ]
          [RANDOM_SEED ] )
 
-Return a random string of given ```` consisting of
-characters from the given ````.  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.
-
-.. _TIMESTAMP:
-
-.. code-block:: cmake
+  Return a random string of given ```` consisting of
+  characters from the given ````.  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.
 
+.. signature::
   string(TIMESTAMP  [] [UTC])
 
-Write a string representation of the current date
-and/or time to the ````.
-
-If the command is unable to obtain a timestamp, the ````
-will be set to the empty string ``""``.
+  Write a string representation of the current date
+  and/or time to the ````.
 
-The optional ``UTC`` flag requests the current date/time representation to
-be in Coordinated Universal Time (UTC) rather than local time.
+  If the command is unable to obtain a timestamp, the ````
+  will be set to the empty string ``""``.
 
-The optional ```` may contain the following format
-specifiers:
-
-``%%``
-  .. versionadded:: 3.8
+  The optional ``UTC`` flag requests the current date/time representation to
+  be in Coordinated Universal Time (UTC) rather than local time.
 
-  A literal percent sign (%).
+  The optional ```` may contain the following format
+  specifiers:
 
-``%d``
-  The day of the current month (01-31).
+  ``%%``
+    .. versionadded:: 3.8
 
-``%H``
-  The hour on a 24-hour clock (00-23).
+    A literal percent sign (%).
 
-``%I``
-  The hour on a 12-hour clock (01-12).
+  ``%d``
+    The day of the current month (01-31).
 
-``%j``
-  The day of the current year (001-366).
+  ``%H``
+    The hour on a 24-hour clock (00-23).
 
-``%m``
-  The month of the current year (01-12).
+  ``%I``
+    The hour on a 12-hour clock (01-12).
 
-``%b``
-  .. versionadded:: 3.7
+  ``%j``
+    The day of the current year (001-366).
 
-  Abbreviated month name (e.g. Oct).
+  ``%m``
+    The month of the current year (01-12).
 
-``%B``
-  .. versionadded:: 3.10
+  ``%b``
+    .. versionadded:: 3.7
 
-  Full month name (e.g. October).
+    Abbreviated month name (e.g. Oct).
 
-``%M``
-  The minute of the current hour (00-59).
+  ``%B``
+    .. versionadded:: 3.10
 
-``%s``
-  .. versionadded:: 3.6
+    Full month name (e.g. October).
 
-  Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
+  ``%M``
+    The minute of the current hour (00-59).
 
-``%S``
-  The second of the current minute.  60 represents a leap second. (00-60)
+  ``%s``
+    .. versionadded:: 3.6
 
-``%f``
-  .. versionadded:: 3.23
+    Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
 
-  The microsecond of the current second (000000-999999).
+  ``%S``
+    The second of the current minute.  60 represents a leap second. (00-60)
 
-``%U``
-  The week number of the current year (00-53).
+  ``%f``
+    .. versionadded:: 3.23
 
-``%V``
-  .. versionadded:: 3.22
+    The microsecond of the current second (000000-999999).
 
-  The ISO 8601 week number of the current year (01-53).
+  ``%U``
+    The week number of the current year (00-53).
 
-``%w``
-  The day of the current week. 0 is Sunday. (0-6)
+  ``%V``
+    .. versionadded:: 3.22
 
-``%a``
-  .. versionadded:: 3.7
+    The ISO 8601 week number of the current year (01-53).
 
-  Abbreviated weekday name (e.g. Fri).
+  ``%w``
+    The day of the current week. 0 is Sunday. (0-6)
 
-``%A``
-  .. versionadded:: 3.10
+  ``%a``
+    .. versionadded:: 3.7
 
-  Full weekday name (e.g. Friday).
+    Abbreviated weekday name (e.g. Fri).
 
-``%y``
-  The last two digits of the current year (00-99).
+  ``%A``
+    .. versionadded:: 3.10
 
-``%Y``
-  The current year.
+    Full weekday name (e.g. Friday).
 
-``%z``
-  .. versionadded:: 3.26
+  ``%y``
+    The last two digits of the current year (00-99).
 
-  The offset of the time zone from UTC, in hours and minutes,
-  with format ``+hhmm`` or ``-hhmm``.
+  ``%Y``
+    The current year.
 
-``%Z``
-  .. versionadded:: 3.26
+  ``%z``
+    .. versionadded:: 3.26
 
-  The time zone name.
+    The offset of the time zone from UTC, in hours and minutes,
+    with format ``+hhmm`` or ``-hhmm``.
 
-Unknown format specifiers will be ignored and copied to the output
-as-is.
+  ``%Z``
+    .. versionadded:: 3.26
 
-If no explicit ```` is given, it will default to:
+    The time zone name.
 
-::
+  Unknown format specifiers will be ignored and copied to the output
+  as-is.
 
-   %Y-%m-%dT%H:%M:%S    for local time.
-   %Y-%m-%dT%H:%M:%SZ   for UTC.
+  If no explicit ```` is given, it will default to:
 
-.. 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.
+  ::
 
-.. _UUID:
+    %Y-%m-%dT%H:%M:%S    for local time.
+    %Y-%m-%dT%H:%M:%SZ   for UTC.
 
-.. code-block:: cmake
+  .. 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.
 
+.. signature::
   string(UUID  NAMESPACE  NAME 
          TYPE  [UPPER])
 
-.. versionadded:: 3.1
+  .. versionadded:: 3.1
 
-Create a universally unique identifier (aka GUID) as per RFC4122
-based on the hash of the combined values of ````
-(which itself has to be a valid UUID) and ````.
-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
-with the optional ``UPPER`` flag.
+  Create a universally unique identifier (aka GUID) as per RFC4122
+  based on the hash of the combined values of ````
+  (which itself has to be a valid UUID) and ````.
+  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
+  with the optional ``UPPER`` flag.
 
 .. _JSON:
 
@@ -586,78 +518,72 @@ Functionality for querying a JSON string.
   option is not present, a fatal error message is generated.  If no error
   occurs, the ```` will be set to ``NOTFOUND``.
 
-.. _JSON_GET:
-.. code-block:: cmake
-
+.. signature::
   string(JSON  [ERROR_VARIABLE ]
          GET   [ ...])
+  :target: JSON GET
 
-Get an element from ```` at the location given
-by the list of ```` arguments.
-Array and object elements will be returned as a JSON string.
-Boolean elements will be returned as ``ON`` or ``OFF``.
-Null elements will be returned as an empty string.
-Number and string types will be returned as strings.
-
-.. _JSON_TYPE:
-.. code-block:: cmake
+  Get an element from ```` at the location given
+  by the list of ```` arguments.
+  Array and object elements will be returned as a JSON string.
+  Boolean elements will be returned as ``ON`` or ``OFF``.
+  Null elements will be returned as an empty string.
+  Number and string types will be returned as strings.
 
+.. signature::
   string(JSON  [ERROR_VARIABLE ]
          TYPE   [ ...])
+  :target: JSON TYPE
 
-Get the type of an element in ```` at the location
-given by the list of ```` arguments. The ````
-will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``,
-``ARRAY``, or ``OBJECT``.
-
-.. _JSON_MEMBER:
-.. code-block:: cmake
+  Get the type of an element in ```` at the location
+  given by the list of ```` arguments. The ````
+  will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``,
+  ``ARRAY``, or ``OBJECT``.
 
+.. signature::
   string(JSON  [ERROR_VARIABLE ]
          MEMBER 
          [ ...] )
+  :target: JSON MEMBER
 
-Get the name of the ````-th member in ```` at the location
-given by the list of ```` arguments.
-Requires an element of object type.
-
-.. _JSON_LENGTH:
-.. code-block:: cmake
+  Get the name of the ````-th member in ````
+  at the location given by the list of ```` arguments.
+  Requires an element of object type.
 
+.. signature::
   string(JSON  [ERROR_VARIABLE ]
          LENGTH  [ ...])
+  :target: JSON LENGTH
 
-Get the length of an element in ```` at the location
-given by the list of ```` arguments.
-Requires an element of array or object type.
-
-.. _JSON_REMOVE:
-.. code-block:: cmake
+  Get the length of an element in ```` at the location
+  given by the list of ```` arguments.
+  Requires an element of array or object type.
 
+.. signature::
   string(JSON  [ERROR_VARIABLE ]
          REMOVE   [ ...])
+  :target: JSON REMOVE
 
-Remove an element from ```` at the location
-given by the list of ```` arguments. The JSON string
-without the removed element will be stored in ````.
-
-.. _JSON_SET:
-.. code-block:: cmake
+  Remove an element from ```` at the location
+  given by the list of ```` arguments. The JSON string
+  without the removed element will be stored in ````.
 
+.. signature::
   string(JSON  [ERROR_VARIABLE ]
          SET   [ ...] )
+  :target: JSON SET
 
-Set an element in ```` at the location
-given by the list of ```` arguments to ````.
-The contents of ```` should be valid JSON.
-
-.. _JSON_EQUAL:
-.. code-block:: cmake
+  Set an element in ```` at the location
+  given by the list of ```` arguments to ````.
+  The contents of ```` should be valid JSON.
 
+.. signature::
   string(JSON  [ERROR_VARIABLE ]
          EQUAL  )
+  :target: JSON EQUAL
 
-Compare the two JSON objects given by ```` and ````
-for equality.  The contents of ```` and ````
-should be valid JSON.  The ```` will be set to a true value if the
-JSON objects are considered equal, or a false value otherwise.
+  Compare the two JSON objects given by ````
+  and ```` for equality.  The contents of ````
+  and ```` should be valid JSON.  The ````
+  will be set to a true value if the JSON objects are considered equal,
+  or a false value otherwise.
-- 
cgit v0.12