From 765d2768f11641f5d22d8e3203f709fc8cd284ac Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Thu, 4 Aug 2022 19:32:56 +0400 Subject: [PATCH] Help: Turn some mentions of options into links on executables man page --- Help/manual/cmake.1.rst | 38 +++++++++-------- Help/manual/cpack.1.rst | 6 +-- Help/manual/ctest.1.rst | 90 +++++++++++++++++++++++------------------ 3 files changed, 76 insertions(+), 58 deletions(-) diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 53469a41f0..2c2ff5fac6 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -97,8 +97,9 @@ Generator This chooses the kind of buildsystem to generate. See the :manual:`cmake-generators(7)` manual for documentation of all generators. Run ``cmake --help`` to see a list of generators available locally. - Optionally use the ``-G`` option below to specify a generator, or simply - accept the default CMake chooses for the current platform. + Optionally use the :option:`-G ` option below to specify a + generator, or simply accept the default CMake chooses for the current + platform. When using one of the :ref:`Command-Line Build Tool Generators` CMake expects that the environment needed by the compiler toolchain @@ -152,11 +153,11 @@ source and build trees and generate a buildsystem: In all cases the ```` may be zero or more of the `Options`_ below. The above styles for specifying the source and build trees may be mixed. -Paths specified with ``-S`` or ``-B`` are always classified as source or -build trees, respectively. Paths specified with plain arguments are -classified based on their content and the types of paths given earlier. -If only one type of path is given, the current working directory (cwd) -is used for the other. For example: +Paths specified with :option:`-S ` or :option:`-B ` +are always classified as source or build trees, respectively. Paths +specified with plain arguments are classified based on their content +and the types of paths given earlier. If only one type of path is given, +the current working directory (cwd) is used for the other. For example: ============================== ============ =========== Command Line Source Dir Build Dir @@ -214,9 +215,9 @@ Options List ``CACHE`` variables will run CMake and list all the variables from the CMake ``CACHE`` that are not marked as ``INTERNAL`` or :prop_cache:`ADVANCED`. This will effectively display current CMake settings, which can then be - changed with ``-D`` option. Changing some of the variables may result - in more variables being created. If ``A`` is specified, then it will - display also advanced variables. If ``H`` is specified, it will also + changed with :option:`-D ` option. Changing some of the variables + may result in more variables being created. If ``A`` is specified, then it + will display also advanced variables. If ``H`` is specified, it will also display help for each variable. .. option:: -N @@ -307,7 +308,8 @@ Options is an entry in the given comma-separated list of case-sensitive package names. - Like ``--debug-find``, but limiting scope to the specified packages. + Like :option:`--debug-find `, but limiting scope + to the specified packages. .. option:: --debug-find-var=[,...] @@ -315,7 +317,8 @@ Options as the result variable, where ```` is an entry in the given comma-separated list. - Like ``--debug-find``, but limiting scope to the specified variable names. + Like :option:`--debug-find `, but limiting scope + to the specified variable names. .. option:: --trace @@ -327,7 +330,7 @@ Options Put cmake in trace mode. - Like ``--trace``, but with variables expanded. + Like :option:`--trace `, but with variables expanded. .. option:: --trace-format= @@ -461,7 +464,9 @@ Options .. option:: --profiling-output= - Used in conjunction with ``--profiling-format`` to output to a given path. + Used in conjunction with + :option:`--profiling-format ` to output to a + given path. .. option:: --profiling-format= @@ -709,7 +714,7 @@ Available commands are: A JSON object with version information. Keys are: ``string`` - The full version string as displayed by cmake ``--version``. + The full version string as displayed by cmake :option:`--version `. ``major`` The major version number in integer form. ``minor`` @@ -736,7 +741,8 @@ Available commands are: Optional member that may be present when the generator supports platform specification via :variable:`CMAKE_GENERATOR_PLATFORM` - (``-A ...``). The value is a list of platforms known to be supported. + (:option:`-A ... `). The value is a list of platforms known to + be supported. ``extraGenerators`` A list of strings with all the extra generators compatible with the generator. diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index f833f07d2d..4861e952fb 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -26,12 +26,12 @@ All supported generators are specified in the :manual:`cpack-generators ` manual. The command ``cpack --help`` prints a list of generators supported for the target platform. Which of them are to be used can be selected through the :variable:`CPACK_GENERATOR` variable -or through the command-line option ``-G``. +or through the command-line option :option:`-G `. The **cpack** program is steered by a configuration file written in the :manual:`CMake language `. Unless chosen differently -through the command-line option ``--config``, the file ``CPackConfig.cmake`` -in the current directory is used. +through the command-line option :option:`--config `, the +file ``CPackConfig.cmake`` in the current directory is used. In the standard CMake workflow, the file ``CPackConfig.cmake`` is generated by the :manual:`cmake ` executable, provided the :module:`CPack` diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 5d78ccd761..c85982cb2a 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -130,8 +130,9 @@ Options .. option:: --test-load - While running tests in parallel (e.g. with ``-j``), try not to start - tests when they may cause the CPU load to pass above a given threshold. + While running tests in parallel (e.g. with :option:`-j `), try + not to start tests when they may cause the CPU load to pass above a given + threshold. When ``ctest`` is run as a `Dashboard Client`_ this sets the ``TestLoad`` option of the `CTest Test Step`_. @@ -140,8 +141,10 @@ Options Make CTest quiet. This option will suppress all the output. The output log file will - still be generated if the ``--output-log`` is specified. Options such - as ``--verbose``, ``--extra-verbose``, and ``--debug`` are ignored + still be generated if the :option:`--output-log ` is + specified. Options such as :option:`--verbose `, + :option:`--extra-verbose `, and + :option:`--debug ` are ignored if ``--quiet`` is specified. .. option:: -O , --output-log @@ -156,16 +159,16 @@ Options This option tells CTest to write test results to ```` in JUnit XML format. If ```` already exists, it will be overwritten. If using the - ``-S`` option to run a dashboard script, use the ``OUTPUT_JUNIT`` keyword - with the :command:`ctest_test` command instead. + :option:`-S ` option to run a dashboard script, use the + ``OUTPUT_JUNIT`` keyword with the :command:`ctest_test` command instead. .. option:: -N, --show-only[=] Disable actual execution of tests. This option tells CTest to list the tests that would be run but not - actually run them. Useful in conjunction with the ``-R`` and ``-E`` - options. + actually run them. Useful in conjunction with the :option:`-R ` + and :option:`-E ` options. ```` can be one of the following values. @@ -226,11 +229,13 @@ Options .. option:: -FS , --fixture-exclude-setup - Same as ``-FA`` except only matching setup tests are excluded. + Same as :option:`-FA ` except only matching setup tests are + excluded. .. option:: -FC , --fixture-exclude-cleanup - Same as ``-FA`` except only matching cleanup tests are excluded. + Same as :option:`-FA ` except only matching cleanup tests are + excluded. .. option:: -D , --dashboard @@ -249,8 +254,8 @@ Options Define a variable for script mode. Pass in variable values on the command line. Use in conjunction - with ``-S`` to pass variable values to a dashboard script. Parsing ``-D`` - arguments as variable values is only attempted if the value + with :option:`-S ` to pass variable values to a dashboard script. + Parsing ``-D`` arguments as variable values is only attempted if the value following ``-D`` does not match any of the known dashboard types. .. option:: -M , --test-model @@ -259,7 +264,8 @@ Options This option tells CTest to act as a CDash client where the ```` can be ``Experimental``, ``Nightly``, and ``Continuous``. - Combining ``-M`` and ``-T`` is similar to ``-D``. + Combining ``-M`` and :option:`-T ` is similar to + :option:`-D `. See `Dashboard Client`_. @@ -270,7 +276,8 @@ Options This option tells CTest to act as a CDash client and perform some action such as ``start``, ``build``, ``test`` etc. See `Dashboard Client Steps`_ for the full list of actions. - Combining ``-M`` and ``-T`` is similar to ``-D``. + Combining :option:`-M ` and ``-T`` is similar to + :option:`-D `. See `Dashboard Client`_. @@ -290,10 +297,10 @@ Options Execute a dashboard for a configuration. - This option does the same operations as ``-S`` but it will do them in a - separate process. This is primarily useful in cases where the - script may modify the environment and you do not want the modified - environment to impact other ``-S`` scripts. + This option does the same operations as :option:`-S ` but it + will do them in a separate process. This is primarily useful in cases + where the script may modify the environment and you do not want the modified + environment to impact other :option:`-S ` scripts. See `Dashboard Client`_. @@ -309,10 +316,11 @@ Options .. option:: -U, --union - Take the Union of ``-I`` and ``-R``. + Take the Union of :option:`-I ` and :option:`-R `. - When both ``-R`` and ``-I`` are specified by default the intersection of - tests are run. By specifying ``-U`` the union of tests is run instead. + When both :option:`-R ` and :option:`-I ` are specified + by default the intersection of tests are run. By specifying ``-U`` the union + of tests is run instead. .. option:: --rerun-failed @@ -320,10 +328,12 @@ Options This option tells CTest to perform only the tests that failed during its previous run. When this option is specified, CTest ignores all - other options intended to modify the list of tests to run (``-L``, ``-R``, - ``-E``, ``-LE``, ``-I``, etc). In the event that CTest runs and no tests - fail, subsequent calls to CTest with the ``--rerun-failed`` option will run - the set of tests that most recently failed (if any). + other options intended to modify the list of tests to run ( + :option:`-L `, :option:`-R `, :option:`-E `, + :option:`-LE `, :option:`-I `, etc). In the event that + CTest runs and no tests fail, subsequent calls to CTest with the + ``--rerun-failed`` option will run the set of tests that most recently + failed (if any). .. option:: --repeat : @@ -347,7 +357,7 @@ Options .. option:: --repeat-until-fail - Equivalent to ``--repeat until-fail:``. + Equivalent to :option:`--repeat until-fail:\ `. .. option:: --max-width @@ -488,17 +498,17 @@ or excluded from a test run by filtering on the labels. Each individual filter is a regular expression applied to the labels attached to a test. -When ``-L`` is used, in order for a test to be included in a +When :option:`-L ` is used, in order for a test to be included in a test run, each regular expression must match at least one -label. Using more than one ``-L`` option means "match **all** +label. Using more than one :option:`-L ` option means "match **all** of these". -The ``-LE`` option works just like ``-L``, but excludes tests -rather than including them. A test is excluded if each regular -expression matches at least one label. +The :option:`-LE ` option works just like :option:`-L `, +but excludes tests rather than including them. A test is excluded if each +regular expression matches at least one label. -If a test has no labels attached to it, then ``-L`` will never -include that test, and ``-LE`` will never exclude that test. +If a test has no labels attached to it, then :option:`-L ` will never +include that test, and :option:`-LE ` will never exclude that test. As an example of tests with labels, consider five tests, with the following labels: @@ -650,7 +660,8 @@ this mode include: .. option:: --test-command - The command to run as the test step with the ``--build-and-test`` option. + The command to run as the test step with the + :option:`--build-and-test ` option. All arguments following this keyword will be assumed to be part of the test command line, so it must be the last option given. @@ -1101,9 +1112,9 @@ Configuration settings include: ``DefaultCTestConfigurationType`` When the build system to be launched allows build-time selection of the configuration (e.g. ``Debug``, ``Release``), this specifies - the default configuration to be built when no ``-C`` option is - given to the ``ctest`` command. The value will be substituted into - the value of ``MakeCommand`` to replace the literal string + the default configuration to be built when no :option:`-C ` + option is given to the ``ctest`` command. The value will be substituted + into the value of ``MakeCommand`` to replace the literal string ``${CTEST_CONFIGURATION_TYPE}`` if it appears. * `CTest Script`_ variable: :variable:`CTEST_CONFIGURATION_TYPE` @@ -1175,8 +1186,9 @@ Configuration settings include: See `Label and Subproject Summary`_. ``TestLoad`` - While running tests in parallel (e.g. with ``-j``), try not to start - tests when they may cause the CPU load to pass above a given threshold. + While running tests in parallel (e.g. with :option:`-j `), + try not to start tests when they may cause the CPU load to pass above + a given threshold. * `CTest Script`_ variable: :variable:`CTEST_TEST_LOAD` * :module:`CTest` module variable: ``CTEST_TEST_LOAD``