Merge topic 'improve-doc-consistency'

277c12a4c7 Help: Improve command usage formatting consistency

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

Help/command/add_custom_command.rst

@@ -14,18 +14,18 @@ The first signature is for adding a custom command to produce an output:
 
 .. code-block:: cmake
 
-  add_custom_command(OUTPUT output1 [output2 ...]
-                     COMMAND command1 [ARGS] [args1...]
-                     [COMMAND command2 [ARGS] [args2...] ...]
+  add_custom_command(OUTPUT <output1> [<output2> ...]
+                     COMMAND <command1> [ARGS] [<args1>...]
+                     [COMMAND <command2> [ARGS] [<args2>...]] ...
                      [MAIN_DEPENDENCY depend]
-                     [DEPENDS [depends...]]
-                     [BYPRODUCTS [files...]]
-                     [IMPLICIT_DEPENDS <lang1> depend1
-                                      [<lang2> depend2] ...]
-                     [WORKING_DIRECTORY dir]
-                     [COMMENT comment]
-                     [DEPFILE depfile]
-                     [JOB_POOL job_pool]
+                     [DEPENDS <depends>...]
+                     [BYPRODUCTS <files>...]
+                     [IMPLICIT_DEPENDS <lang1> <depend1>
+                                      [<lang2> <depend2>] ...]
+                     [WORKING_DIRECTORY <dir>]
+                     [COMMENT <comment>]
+                     [DEPFILE <depfile>]
+                     [JOB_POOL <job_pool>]
                      [JOB_SERVER_AWARE <bool>]
                      [VERBATIM] [APPEND] [USES_TERMINAL]
                      [CODEGEN]
@@ -593,11 +593,11 @@ target is already built, the command will not execute.
 
   add_custom_command(TARGET <target>
                      PRE_BUILD | PRE_LINK | POST_BUILD
-                     COMMAND command1 [ARGS] [args1...]
-                     [COMMAND command2 [ARGS] [args2...] ...]
-                     [BYPRODUCTS [files...]]
-                     [WORKING_DIRECTORY dir]
-                     [COMMENT comment]
+                     COMMAND <command1> [ARGS] [<args1>...]
+                     [COMMAND <command2> [ARGS] [<args2>...]] ...
+                     [BYPRODUCTS <files>...]
+                     [WORKING_DIRECTORY <dir>]
+                     [COMMENT <comment>]
                      [VERBATIM]
                      [COMMAND_EXPAND_LISTS]
                      [USES_TERMINAL])

Help/command/add_custom_target.rst

@@ -5,17 +5,17 @@ Add a target with no output so it will always be built.
 
 .. code-block:: cmake
 
-  add_custom_target(Name [ALL] [command1 [args1...]]
-                    [COMMAND command2 [args2...] ...]
-                    [DEPENDS depend depend depend ...]
-                    [BYPRODUCTS [files...]]
-                    [WORKING_DIRECTORY dir]
-                    [COMMENT comment]
-                    [JOB_POOL job_pool]
+  add_custom_target(Name [ALL] [command1 [<args1>...]]
+                    [COMMAND command2 [<args2>...]] ...
+                    [DEPENDS <depend>...]
+                    [BYPRODUCTS <file>...]
+                    [WORKING_DIRECTORY <dir>]
+                    [COMMENT <comment>]
+                    [JOB_POOL <job_pool>]
                     [JOB_SERVER_AWARE <bool>]
                     [VERBATIM] [USES_TERMINAL]
                     [COMMAND_EXPAND_LISTS]
-                    [SOURCES src1 [src2...]])
+                    [SOURCES <source>...])
 
 Adds a target with the given name that executes the given commands.
 The target has no output file and is *always considered out of date*

Help/command/configure_file.rst

@@ -193,7 +193,7 @@ specify the output directory as an include directory:
 
 .. code-block:: cmake
 
-  target_include_directories(<target> [SYSTEM] <INTERFACE|PUBLIC|PRIVATE> "${CMAKE_CURRENT_BINARY_DIR}")
+  target_include_directories(<target> [SYSTEM] {INTERFACE|PUBLIC|PRIVATE} "${CMAKE_CURRENT_BINARY_DIR}")
 
 so that sources may include the header as ``#include <foo.h>``.
 

Help/command/define_property.rst

@@ -8,8 +8,8 @@ Define and document custom properties.
   define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
                    TEST | VARIABLE | CACHED_VARIABLE>
                    PROPERTY <name> [INHERITED]
-                   [BRIEF_DOCS <brief-doc> [docs...]]
-                   [FULL_DOCS <full-doc> [docs...]]
+                   [BRIEF_DOCS <brief-doc> [<docs>...]]
+                   [FULL_DOCS <full-doc> [<docs>...]]
                    [INITIALIZE_FROM_VARIABLE <variable>])
 
 Defines one property in a scope for use with the :command:`set_property` and

Help/command/find_file.rst

@@ -2,7 +2,7 @@ find_file
 ---------
 
 .. |FIND_XXX| replace:: find_file
-.. |NAMES| replace:: NAMES name1 [name2 ...]
+.. |NAMES| replace:: NAMES <name>...
 .. |SEARCH_XXX| replace:: full path to a file
 .. |SEARCH_XXX_DESC| replace:: full path to a named file
 .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``

Help/command/find_library.rst

@@ -2,7 +2,7 @@ find_library
 ------------
 
 .. |FIND_XXX| replace:: find_library
-.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR]
+.. |NAMES| replace:: NAMES <name>... [NAMES_PER_DIR]
 .. |SEARCH_XXX| replace:: library
 .. |SEARCH_XXX_DESC| replace:: library
 .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib``

Help/command/find_package.rst

@@ -137,10 +137,10 @@ Basic Signature
 
 .. code-block:: cmake
 
-  find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
-               [REQUIRED|OPTIONAL] [[COMPONENTS] [components...]]
-               [OPTIONAL_COMPONENTS components...]
-               [REGISTRY_VIEW  (64|32|64_32|32_64|HOST|TARGET|BOTH)]
+  find_package(<PackageName> [<version>] [EXACT] [QUIET] [MODULE]
+               [REQUIRED|OPTIONAL] [[COMPONENTS] <component>...]
+               [OPTIONAL_COMPONENTS <component>...]
+               [REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}]
                [GLOBAL]
                [NO_POLICY_SCOPE]
                [BYPASS_PROVIDER]
@@ -211,7 +211,7 @@ target package:
 
 .. _FIND_PACKAGE_VERSION_FORMAT:
 
-The ``[version]`` argument requests a version with which the package found
+The ``<version>`` argument requests a version with which the package found
 should be compatible. There are two possible forms in which it may be
 specified:
 
@@ -236,10 +236,10 @@ specified:
 The ``EXACT`` option requests that the version be matched exactly. This option
 is incompatible with the specification of a version range.
 
-If no ``[version]`` and/or component list is given to a recursive invocation
+If no ``<version>`` and/or component list is given to a recursive invocation
 inside a find-module, the corresponding arguments are forwarded
 automatically from the outer call (including the ``EXACT`` flag for
-``[version]``).
+``<version>``).
 
 See the :command:`cmake_policy` command documentation for discussion
 of the ``NO_POLICY_SCOPE`` option.
@@ -275,18 +275,18 @@ Full Signature
 .. code-block:: cmake
 
   find_package(<PackageName> [version] [EXACT] [QUIET]
-               [REQUIRED|OPTIONAL] [[COMPONENTS] [components...]]
-               [OPTIONAL_COMPONENTS components...]
+               [REQUIRED|OPTIONAL] [[COMPONENTS] <component>...]
+               [OPTIONAL_COMPONENTS <component>...]
                [CONFIG|NO_MODULE]
                [GLOBAL]
                [NO_POLICY_SCOPE]
                [BYPASS_PROVIDER]
-               [NAMES name1 [name2 ...]]
-               [CONFIGS config1 [config2 ...]]
-               [HINTS path1 [path2 ...]]
-               [PATHS path1 [path2 ...]]
-               [REGISTRY_VIEW  (64|32|64_32|32_64|HOST|TARGET|BOTH)]
-               [PATH_SUFFIXES suffix1 [suffix2 ...]]
+               [NAMES <name>...]
+               [CONFIGS <config>...]
+               [HINTS <path>...]
+               [PATHS <path>...]
+               [REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}]
+               [PATH_SUFFIXES <suffix>...]
                [NO_DEFAULT_PATH]
                [NO_PACKAGE_ROOT_PATH]
                [NO_CMAKE_PATH]
@@ -690,7 +690,7 @@ Config Mode Version Selection
   regardless of whether the :ref:`full <full signature>` or
   :ref:`basic <basic signature>` signature was given.
 
-When the ``[version]`` argument is given, Config mode will only find a
+When the ``<version>`` argument is given, Config mode will only find a
 version of the package that claims compatibility with the requested
 version (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`).  If
 the ``EXACT`` option is given, only a version of the package claiming an exact
@@ -987,7 +987,7 @@ the full requested version string as specified.
 In Module mode the loaded find module is responsible to honor the
 request detailed by these variables; see the find module for details.
 In Config mode ``find_package`` handles ``REQUIRED``, ``QUIET``, and
-``[version]`` options automatically but leaves it to the package
+``<version>`` options automatically but leaves it to the package
 configuration file to handle components in a way that makes sense
 for the package.  The package configuration file may set
 ``<PackageName>_FOUND`` to false to tell ``find_package`` that component

Help/command/find_path.rst

@@ -2,7 +2,7 @@ find_path
 ---------
 
 .. |FIND_XXX| replace:: find_path
-.. |NAMES| replace:: NAMES name1 [name2 ...]
+.. |NAMES| replace:: NAMES <name>...
 .. |SEARCH_XXX| replace:: file in a directory
 .. |SEARCH_XXX_DESC| replace:: directory containing the named file
 .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``

Help/command/find_program.rst

@@ -2,7 +2,7 @@ find_program
 ------------
 
 .. |FIND_XXX| replace:: find_program
-.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR]
+.. |NAMES| replace:: NAMES <name>... [NAMES_PER_DIR]
 .. |SEARCH_XXX| replace:: program
 .. |SEARCH_XXX_DESC| replace:: program
 .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin``

Help/command/include/FIND_XXX.rst

@@ -2,7 +2,7 @@ A short-hand signature is:
 
 .. parsed-literal::
 
-   |FIND_XXX| (<VAR> name1 [path1 path2 ...])
+   |FIND_XXX| (<VAR> <name> [<path>...])
 
 The general signature is:
 
@@ -10,12 +10,12 @@ The general signature is:
 
    |FIND_XXX| (
              <VAR>
-             name | |NAMES|
-             [HINTS [path | ENV var]...]
-             [PATHS [path | ENV var]...]
-             [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
-             [PATH_SUFFIXES suffix1 [suffix2 ...]]
-             [VALIDATOR function]
+             {<name> | |NAMES|}
+             [HINTS {<path> | ENV <var>}...]
+             [PATHS {<path> | ENV <var>}...]
+             [REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}]
+             [PATH_SUFFIXES <suffix>...]
+             [VALIDATOR <function>]
              [DOC "cache documentation string"]
              [NO_CACHE]
              [REQUIRED|OPTIONAL]

Help/command/include/FIND_XXX_ORDER.rst

@@ -5,7 +5,7 @@ multiple times and using the ``NO_*`` options:
 
 .. parsed-literal::
 
-   |FIND_XXX| (|FIND_ARGS_XXX| PATHS paths... NO_DEFAULT_PATH)
+   |FIND_XXX| (|FIND_ARGS_XXX| PATHS <paths>... NO_DEFAULT_PATH)
    |FIND_XXX| (|FIND_ARGS_XXX|)
 
 Once one of the calls succeeds the result variable will be set

Help/command/install.rst

@@ -551,7 +551,7 @@ Signatures
   programs that are not targets, such as shell scripts.  Use the ``TARGETS``
   form to install targets built within the project.
 
-  The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use
+  The list of files given to ``FILES`` or ``PROGRAMS`` may use
   "generator expressions" with the syntax ``$<...>``.  See the
   :manual:`cmake-generator-expressions(7)` manual for available expressions.
   However, if any item begins in a generator expression it must evaluate

Help/command/set_property.rst

@@ -5,19 +5,19 @@ Set a named property in a given scope.
 
 .. code-block:: cmake
 
-  set_property(<GLOBAL                                     |
-                DIRECTORY [<dir>]                          |
-                TARGET    [<target1> ...]                  |
-                FILE_SET  [<file_set> ...] TARGET <target> |
-                SOURCE    [<src1> ...]
+  set_property({GLOBAL                                    |
+                DIRECTORY [<dir>]                         |
+                TARGET    <target>...                     |
+                FILE_SET  <file_set>... TARGET <target>   |
+                SOURCE    <source>...
                           [DIRECTORY <dirs> ...]
-                          [TARGET_DIRECTORY <targets> ...] |
-                INSTALL   [<file1> ...]                    |
-                TEST      [<test1> ...]
-                          [DIRECTORY <dir>]                |
-                CACHE     [<entry1> ...]>
+                          [TARGET_DIRECTORY <targets>...] |
+                INSTALL   <file>...                       |
+                TEST      <test>...
+                          [DIRECTORY <dir>]               |
+                CACHE     <entry>...}
                [APPEND] [APPEND_STRING]
-               PROPERTY <name> [<value1> ...])
+               PROPERTY <name> [<value>...])
 
 Sets one property on zero or more objects of a scope.
 

Help/command/target_compile_definitions.rst

@@ -6,8 +6,8 @@ Add compile definitions to a target.
 .. code-block:: cmake
 
   target_compile_definitions(<target>
-    <INTERFACE|PUBLIC|PRIVATE> [items1...]
-    [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
+    <INTERFACE|PUBLIC|PRIVATE> <definition>...
+    [<INTERFACE|PUBLIC|PRIVATE> <definition>... ...])
 
 Specifies compile definitions to use when compiling a given ``<target>``.  The
 named ``<target>`` must have been created by a command such as

Help/command/target_compile_features.rst

@@ -7,7 +7,9 @@ Add expected compiler features to a target.
 
 .. code-block:: cmake
 
-  target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
+  target_compile_features(<target>
+    {INTERFACE|PUBLIC|PRIVATE} <feature>...
+    [{INTERFACE|PUBLIC|PRIVATE} <feature>...]...)
 
 Specifies compiler features required when compiling a given target.  If the
 feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES`,

Help/command/target_compile_options.rst

@@ -6,8 +6,8 @@ Add compile options to a target.
 .. code-block:: cmake
 
   target_compile_options(<target> [BEFORE]
-    <INTERFACE|PUBLIC|PRIVATE> [items1...]
-    [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
+    {INTERFACE|PUBLIC|PRIVATE} <item>...
+    [{INTERFACE|PUBLIC|PRIVATE} <item>...]...)
 
 Adds options to the :prop_tgt:`COMPILE_OPTIONS` or
 :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties. These options

Help/command/target_include_directories.rst

@@ -6,8 +6,8 @@ Add include directories to a target.
 .. code-block:: cmake
 
   target_include_directories(<target> [SYSTEM] [AFTER|BEFORE]
-    <INTERFACE|PUBLIC|PRIVATE> [items1...]
-    [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
+    {INTERFACE|PUBLIC|PRIVATE} <dir...
+    [{INTERFACE|PUBLIC|PRIVATE} <dir>...]...)
 
 Specifies include directories to use when compiling a given target.
 The named ``<target>`` must have been created by a command such

Help/command/target_link_directories.rst

@@ -8,8 +8,8 @@ Add link directories to a target.
 .. code-block:: cmake
 
   target_link_directories(<target> [BEFORE]
-    <INTERFACE|PUBLIC|PRIVATE> [items1...]
-    [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
+    {INTERFACE|PUBLIC|PRIVATE} <dir>...
+    [{INTERFACE|PUBLIC|PRIVATE} <dir>...]...)
 
 Specifies the paths in which the linker should search for libraries when
 linking a given target.  Each item can be an absolute or relative path,

Help/command/target_link_libraries.rst

@@ -158,8 +158,8 @@ Libraries for a Target and/or its Dependents
 .. code-block:: cmake
 
   target_link_libraries(<target>
-                        <PRIVATE|PUBLIC|INTERFACE> <item>...
-                       [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
+    {INTERFACE|PUBLIC|PRIVATE} <item>...
+    [{INTERFACE|PUBLIC|PRIVATE} <item>...]...)
 
 The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE``
 :ref:`scope <Target Command Scope>` keywords can be used to

Help/command/target_link_options.rst

@@ -9,8 +9,8 @@ library target.
 .. code-block:: cmake
 
   target_link_options(<target> [BEFORE]
-    <INTERFACE|PUBLIC|PRIVATE> [items1...]
-    [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
+    {INTERFACE|PUBLIC|PRIVATE} <item>...
+    [{INTERFACE|PUBLIC|PRIVATE} <item>...]...)
 
 The named ``<target>`` must have been created by a command such as
 :command:`add_executable` or :command:`add_library` and must not be an

Help/command/target_precompile_headers.rst

@@ -15,8 +15,8 @@ Main Form
 .. code-block:: cmake
 
   target_precompile_headers(<target>
-    <INTERFACE|PUBLIC|PRIVATE> [header1...]
-    [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])
+    {INTERFACE|PUBLIC|PRIVATE} <header>...
+    [{INTERFACE|PUBLIC|PRIVATE} <header>...]...)
 
 The command adds header files to the :prop_tgt:`PRECOMPILE_HEADERS` and/or
 :prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties of ``<target>``.

Help/command/target_sources.rst

@@ -8,8 +8,8 @@ Add sources to a target.
 .. code-block:: cmake
 
   target_sources(<target>
-    <INTERFACE|PUBLIC|PRIVATE> [items1...]
-    [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
+    {INTERFACE|PUBLIC|PRIVATE} <source>...
+    [{INTERFACE|PUBLIC|PRIVATE} <source>...]...)
 
 Specifies sources to use when building a target and/or its dependents.
 The named ``<target>`` must have been created by a command such as
@@ -70,7 +70,7 @@ File Sets
 .. code-block:: cmake
 
   target_sources(<target>
-    [<INTERFACE|PUBLIC|PRIVATE>
+    [{INTERFACE|PUBLIC|PRIVATE}
      [FILE_SET <set> [TYPE <type>] [BASE_DIRS <dirs>...] [FILES <files>...]]...
     ]...)
 

Help/command/try_compile.rst

@@ -71,10 +71,10 @@ Try Compiling Source Files
 
   try_compile(<compileResultVar>
               [SOURCES_TYPE <type>]
-              <SOURCES <srcfile...>                 |
+              {SOURCES <srcfile>...                 |
                SOURCE_FROM_CONTENT <name> <content> |
                SOURCE_FROM_VAR <name> <var>         |
-               SOURCE_FROM_FILE <name> <path>       >...
+               SOURCE_FROM_FILE <name> <path>       }...
               [LOG_DESCRIPTION <text>]
               [NO_CACHE]
               [NO_LOG]
@@ -130,7 +130,7 @@ The signature above is recommended for clarity.
 
 .. code-block:: cmake
 
-  try_compile(<compileResultVar> <bindir> <srcfile|SOURCES srcfile...>
+  try_compile(<compileResultVar> <bindir> {<srcfile>|SOURCES <srcfile>...}
               [CMAKE_FLAGS <flags>...]
               [COMPILE_DEFINITIONS <defs>...]
               [LINK_OPTIONS <options>...]

Help/command/try_run.rst

@@ -14,10 +14,10 @@ Try Compiling and Running Source Files
 
   try_run(<runResultVar> <compileResultVar>
           [SOURCES_TYPE <type>]
-          <SOURCES <srcfile...>                 |
+          {SOURCES <srcfile>...                 |
            SOURCE_FROM_CONTENT <name> <content> |
            SOURCE_FROM_VAR <name> <var>         |
-           SOURCE_FROM_FILE <name> <path>       >...
+           SOURCE_FROM_FILE <name> <path>       }...
           [LOG_DESCRIPTION <text>]
           [NO_CACHE]
           [NO_LOG]
@@ -63,7 +63,7 @@ The signature above is recommended for clarity.
 .. code-block:: cmake
 
   try_run(<runResultVar> <compileResultVar>
-          <bindir> <srcfile|SOURCES srcfile...>
+          <bindir> {<srcfile>|SOURCES <srcfile>...}
           [CMAKE_FLAGS <flags>...]
           [COMPILE_DEFINITIONS <defs>...]
           [LINK_OPTIONS <options>...]

Utilities/Sphinx/cmake.py

@@ -101,8 +101,12 @@ CMakeLexer.tokens["root"] = [
   (r'(?s)"(\\"|[^"])*"', String),
   (r'\.\.\.', Name.Variable),
   # <..|..> is different from <expr>
-  (r'<', Operator, '#push'),
-  (r'>', Operator, '#pop'),
+  # TODO: <..|..> should be {..|..}; remove when all instances are converted?
+  (r'<', Punctuation, '#push'),
+  (r'>', Punctuation, '#pop'),
+  # {..|..}
+  (r'\{', Punctuation, '#push'),
+  (r'\}', Punctuation, '#pop'),
   (r'\n', Whitespace),
   (r'[ \t]+', Whitespace),
   (r'#.*\n', Comment),