From 7f4b90a3a6d9adf34bc1b89c630107bf50fb0237 Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Tue, 9 Aug 2022 22:50:10 +0400 Subject: Help: Fix `ctest` options description Missed empty line after `.. option::` and the next paragraph. --- Help/manual/ctest.1.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index c85982c..ebcf517 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -76,6 +76,7 @@ Options displayed. This option will show all test output. .. option:: -VV, --extra-verbose + Enable more verbose output from tests. Test output is normally suppressed and only summary information is @@ -138,6 +139,7 @@ Options ``TestLoad`` option of the `CTest Test Step`_. .. option:: -Q, --quiet + Make CTest quiet. This option will suppress all the output. The output log file will @@ -406,7 +408,7 @@ Options .. option:: --test-dir -Specify the directory in which to look for tests. + Specify the directory in which to look for tests. .. option:: --test-output-size-passed -- cgit v0.12 From 798834ef6322e7cac19e3d54e4fd80ed11a7c933 Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Tue, 9 Aug 2022 22:56:04 +0400 Subject: =?UTF-8?q?Help:=20``=20=E2=86=92=20``=20for=20`--help*`?= =?UTF-8?q?=20option=20descriptions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Help/manual/OPTIONS_HELP.txt | 40 ++++++++++++++++++++-------------------- Source/cmDocumentation.cxx | 42 ++++++++++++++++++++++-------------------- 2 files changed, 42 insertions(+), 40 deletions(-) diff --git a/Help/manual/OPTIONS_HELP.txt b/Help/manual/OPTIONS_HELP.txt index 92bdf1e..00e5714 100644 --- a/Help/manual/OPTIONS_HELP.txt +++ b/Help/manual/OPTIONS_HELP.txt @@ -1,4 +1,4 @@ -.. |file| replace:: The help is printed to a named ile if given. +.. |file| replace:: The help is printed to a named ```` if given. .. option:: --help, -help, -usage, -h, -H, /? @@ -6,28 +6,28 @@ Usage describes the basic command line interface and its options. -.. option:: --version, -version, /V [] +.. option:: --version, -version, /V [] Show program name/version banner and exit. If a file is specified, the version is written into it. |file| -.. option:: --help-full [] +.. option:: --help-full [] Print all help manuals and exit. All manuals are printed in a human-readable text format. |file| -.. option:: --help-manual [] +.. option:: --help-manual [] Print one help manual and exit. The specified manual is printed in a human-readable text format. |file| -.. option:: --help-manual-list [] +.. option:: --help-manual-list [] List help manuals available and exit. @@ -35,7 +35,7 @@ using the ``--help-manual`` option followed by a manual name. |file| -.. option:: --help-command [] +.. option:: --help-command [] Print help for one command and exit. @@ -43,7 +43,7 @@ printed in a human-readable text format. |file| -.. option:: --help-command-list [] +.. option:: --help-command-list [] List commands with help available and exit. @@ -51,7 +51,7 @@ using the ``--help-command`` option followed by a command name. |file| -.. option:: --help-commands [] +.. option:: --help-commands [] Print cmake-commands manual and exit. @@ -59,7 +59,7 @@ human-readable text format. |file| -.. option:: --help-module [] +.. option:: --help-module [] Print help for one module and exit. @@ -67,7 +67,7 @@ in a human-readable text format. |file| -.. option:: --help-module-list [] +.. option:: --help-module-list [] List modules with help available and exit. @@ -75,7 +75,7 @@ using the ``--help-module`` option followed by a module name. |file| -.. option:: --help-modules [] +.. option:: --help-modules [] Print cmake-modules manual and exit. @@ -83,7 +83,7 @@ text format. |file| -.. option:: --help-policy [] +.. option:: --help-policy [] Print help for one policy and exit. @@ -91,7 +91,7 @@ printed in a human-readable text format. |file| -.. option:: --help-policy-list [] +.. option:: --help-policy-list [] List policies with help available and exit. @@ -99,7 +99,7 @@ using the ``--help-policy`` option followed by a policy name. |file| -.. option:: --help-policies [] +.. option:: --help-policies [] Print cmake-policies manual and exit. @@ -107,7 +107,7 @@ human-readable text format. |file| -.. option:: --help-property [] +.. option:: --help-property [] Print help for one property and exit. @@ -115,7 +115,7 @@ printed in a human-readable text format. |file| -.. option:: --help-property-list [] +.. option:: --help-property-list [] List properties with help available and exit. @@ -123,7 +123,7 @@ using the ``--help-property`` option followed by a property name. |file| -.. option:: --help-properties [] +.. option:: --help-properties [] Print cmake-properties manual and exit. @@ -131,7 +131,7 @@ human-readable text format. |file| -.. option:: --help-variable [] +.. option:: --help-variable [] Print help for one variable and exit. @@ -139,7 +139,7 @@ printed in a human-readable text format. |file| -.. option:: --help-variable-list [] +.. option:: --help-variable-list [] List variables with help available and exit. @@ -147,7 +147,7 @@ using the ``--help-variable`` option followed by a variable name. |file| -.. option:: --help-variables [] +.. option:: --help-variables [] Print cmake-variables manual and exit. diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index 3619ade..d466a12 100644 --- a/Source/cmDocumentation.cxx +++ b/Source/cmDocumentation.cxx @@ -17,30 +17,32 @@ #include "cmVersion.h" static const char* cmDocumentationStandardOptions[][2] = { - { "--help,-help,-usage,-h,-H,/?", "Print usage information and exit." }, - { "--version,-version,/V []", "Print version number and exit." }, - { "--help-full []", "Print all help manuals and exit." }, - { "--help-manual []", "Print one help manual and exit." }, - { "--help-manual-list []", "List help manuals available and exit." }, - { "--help-command []", "Print help for one command and exit." }, - { "--help-command-list []", + { "-h,-H,--help,-help,-usage,/?", "Print usage information and exit." }, + { "--version,-version,/V []", "Print version number and exit." }, + { "--help-full []", "Print all help manuals and exit." }, + { "--help-manual []", "Print one help manual and exit." }, + { "--help-manual-list []", "List help manuals available and exit." }, + { "--help-command []", "Print help for one command and exit." }, + { "--help-command-list []", "List commands with help available and exit." }, - { "--help-commands []", "Print cmake-commands manual and exit." }, - { "--help-module []", "Print help for one module and exit." }, - { "--help-module-list []", "List modules with help available and exit." }, - { "--help-modules []", "Print cmake-modules manual and exit." }, - { "--help-policy []", "Print help for one policy and exit." }, - { "--help-policy-list []", + { "--help-commands []", "Print cmake-commands manual and exit." }, + { "--help-module []", "Print help for one module and exit." }, + { "--help-module-list []", + "List modules with help available and exit." }, + { "--help-modules []", "Print cmake-modules manual and exit." }, + { "--help-policy []", "Print help for one policy and exit." }, + { "--help-policy-list []", "List policies with help available and exit." }, - { "--help-policies []", "Print cmake-policies manual and exit." }, - { "--help-property []", "Print help for one property and exit." }, - { "--help-property-list []", + { "--help-policies []", "Print cmake-policies manual and exit." }, + { "--help-property []", + "Print help for one property and exit." }, + { "--help-property-list []", "List properties with help available and exit." }, - { "--help-properties []", "Print cmake-properties manual and exit." }, - { "--help-variable var []", "Print help for one variable and exit." }, - { "--help-variable-list []", + { "--help-properties []", "Print cmake-properties manual and exit." }, + { "--help-variable var []", "Print help for one variable and exit." }, + { "--help-variable-list []", "List variables with help available and exit." }, - { "--help-variables []", "Print cmake-variables manual and exit." }, + { "--help-variables []", "Print cmake-variables manual and exit." }, { nullptr, nullptr } }; -- cgit v0.12 From 5a20d4c2503ca57cf5d5ff3152c14c12b31d8ccd Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Tue, 9 Aug 2022 23:07:14 +0400 Subject: Help: Consistent spaces in option args --- Help/manual/ctest.1.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index ebcf517..02bdcaf 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -809,7 +809,7 @@ Run the ``ctest`` command with the current working directory set to the build tree and use one of these signatures:: ctest -D [] - ctest -M [ -T ]... + ctest -M [-T ]... The ```` must be one of the above `Dashboard Client Modes`_, and each ```` must be one of the above `Dashboard Client Steps`_. -- cgit v0.12 From 57f23fa8fcd508ac26a2e87deae0704c11e77933 Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Tue, 9 Aug 2022 23:20:57 +0400 Subject: =?UTF-8?q?Help:=20`{<=E2=80=A6>=20|=20<=E2=80=A6>}`=20=E2=86=92?= =?UTF-8?q?=20`<=E2=80=A6|=E2=80=A6>`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The form of alternative names for "placeholders" has been used already (e.g., `` in the `cmake(1)` manual). --- Help/manual/ccmake.1.rst | 2 +- Help/manual/cmake-gui.1.rst | 2 +- Help/manual/cmake.1.rst | 3 +-- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst index bc411a4..cd66d51 100644 --- a/Help/manual/ccmake.1.rst +++ b/Help/manual/ccmake.1.rst @@ -8,7 +8,7 @@ Synopsis .. parsed-literal:: - ccmake [] { | } + ccmake [] Description =========== diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index 493b625..dd0eeca 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -9,7 +9,7 @@ Synopsis .. parsed-literal:: cmake-gui [] - cmake-gui [] { | } + cmake-gui [] cmake-gui [] -S -B cmake-gui [] --browse-manual diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index ff6ae80..c5d3016 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -9,8 +9,7 @@ Synopsis .. parsed-literal:: `Generate a Project Buildsystem`_ - cmake [] - cmake [] + cmake [] cmake [] -S -B `Build a Project`_ -- cgit v0.12 From 28ecfd1690fe949274a7be8cd1869b68bef7f64d Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Tue, 9 Aug 2022 23:33:17 +0400 Subject: Help: Short options first, then long, then Windows style --- Help/manual/OPTIONS_HELP.txt | 4 ++-- Help/manual/cmake.1.rst | 2 +- Help/manual/cpack.1.rst | 2 +- Source/CPack/cpack.cxx | 2 +- Source/cmakemain.cxx | 4 ++-- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Help/manual/OPTIONS_HELP.txt b/Help/manual/OPTIONS_HELP.txt index 00e5714..0e51a7f 100644 --- a/Help/manual/OPTIONS_HELP.txt +++ b/Help/manual/OPTIONS_HELP.txt @@ -1,12 +1,12 @@ .. |file| replace:: The help is printed to a named ```` if given. -.. option:: --help, -help, -usage, -h, -H, /? +.. option:: -h, -H, --help, -help, -usage, /? Print usage information and exit. Usage describes the basic command line interface and its options. -.. option:: --version, -version, /V [] +.. option:: -version [], --version [], /V [] Show program name/version banner and exit. diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index c5d3016..26f9d7c 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -545,7 +545,7 @@ following options: Some native build tools always build in parallel. The use of ```` value of ``1`` can be used to limit to a single job. -.. option:: --target ..., -t ... +.. option:: -t ..., --target ... Build ```` instead of the default target. Multiple targets may be given, separated by spaces. diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 4861e95..a95df8b 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -73,7 +73,7 @@ Options details. By default, ``CPackConfig.cmake`` in the current directory will be used. -.. option:: --verbose, -V +.. option:: -V, --verbose Run ``cpack`` with verbose output. This can be used to show more details from the package generation tools and is suitable for project developers. diff --git a/Source/CPack/cpack.cxx b/Source/CPack/cpack.cxx index 221f7dd..4d9a42a 100644 --- a/Source/CPack/cpack.cxx +++ b/Source/CPack/cpack.cxx @@ -50,7 +50,7 @@ const char* cmDocumentationOptions[][2] = { { "-C ", "Specify the project configuration" }, { "-D =", "Set a CPack variable." }, { "--config ", "Specify the config file." }, - { "--verbose,-V", "Enable verbose output" }, + { "-V,--verbose", "Enable verbose output" }, { "--trace", "Put underlying cmake scripts in trace mode." }, { "--trace-expand", "Put underlying cmake scripts in expanded trace mode." }, { "--debug", "Enable debug output (for CPack developers)" }, diff --git a/Source/cmakemain.cxx b/Source/cmakemain.cxx index c83508b..5837bc5 100644 --- a/Source/cmakemain.cxx +++ b/Source/cmakemain.cxx @@ -627,14 +627,14 @@ int do_build(int ac, char const* const* av) " specifies a default parallel level when this " "option\n" " is not given.\n" - " --target ..., -t ... \n" + " -t ..., --target ...\n" " = Build instead of default targets.\n" " --config = For multi-configuration tools, choose .\n" " --clean-first = Build target 'clean' first, then build.\n" " (To clean only, use --target 'clean'.)\n" " --resolve-package-references={on|only|off}\n" " = Restore/resolve package references during build.\n" - " --verbose, -v = Enable verbose output - if supported - including\n" + " -v, --verbose = Enable verbose output - if supported - including\n" " the build commands to be executed. \n" " -- = Pass remaining options to the native tool.\n" ; -- cgit v0.12 From c401fc5dee64e5a678f74cc745296c902e7a4f88 Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Tue, 9 Aug 2022 23:34:20 +0400 Subject: Help: Simplify optional repeating option Similar form has already been used in the `ctest -M [-T ]...` synopsis and looks quite clean w/o extra characters. --- Help/manual/cmake.1.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 26f9d7c..755e1c4 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -22,7 +22,7 @@ Synopsis cmake --open `Run a Script`_ - cmake [{-D =}...] -P + cmake [-D =]... -P `Run a Command-Line Tool`_ cmake -E [] @@ -668,7 +668,7 @@ Run a Script .. code-block:: shell - cmake [{-D =}...] -P [-- ...] + cmake [-D =]... -P [-- ...] .. option:: -D = -- cgit v0.12 From 4c1008d739ebbe677a877256f0e3f1e37fe9ffee Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Wed, 10 Aug 2022 00:08:04 +0400 Subject: Help: Use `:option:` role to reference `ctest` options --- Help/manual/cmake-presets.7.rst | 2 +- Help/prop_test/LABELS.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 290c2ba..ea43b14 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -570,7 +570,7 @@ that may contain the following fields: ``name`` A required string representing the machine-friendly name of the preset. - This identifier is used in the :ref:`ctest --preset ` option. + This identifier is used in the :option:`ctest --preset` option. There must not be two test presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. However, a test preset may have the same name as a configure or build preset. diff --git a/Help/prop_test/LABELS.rst b/Help/prop_test/LABELS.rst index a06f152..d827adc 100644 --- a/Help/prop_test/LABELS.rst +++ b/Help/prop_test/LABELS.rst @@ -4,7 +4,7 @@ LABELS Specify a list of text labels associated with a test. The labels are reported in both the ``ctest`` output summary and in dashboard submissions. They can also be used to filter the set of tests to be executed (see the -``ctest -L`` and ``ctest -LE`` :ref:`CTest Options`). +:option:`ctest -L` and :option:`ctest -LE` options). See :ref:`Additional Labels` for adding labels to a test dynamically during test execution. -- cgit v0.12 From 146e4e6bad0f8984ccdc94eec0229198e1063efe Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Wed, 10 Aug 2022 00:17:38 +0400 Subject: Help: Split `ctest` options into groups like `cmake` man page has Co-Authored-By: Craig Scott --- Help/manual/OPTIONS_HELP.txt | 14 ++-- Help/manual/ctest.1.rst | 183 +++++++++++++++++++++++-------------------- 2 files changed, 106 insertions(+), 91 deletions(-) diff --git a/Help/manual/OPTIONS_HELP.txt b/Help/manual/OPTIONS_HELP.txt index 0e51a7f..78ee245 100644 --- a/Help/manual/OPTIONS_HELP.txt +++ b/Help/manual/OPTIONS_HELP.txt @@ -1,4 +1,9 @@ -.. |file| replace:: The help is printed to a named ```` if given. +.. |file| replace:: The output is printed to a named ```` if given. + +.. option:: -version [], --version [], /V [] + + Show program name/version banner and exit. + |file| .. option:: -h, -H, --help, -help, -usage, /? @@ -6,13 +11,6 @@ Usage describes the basic command line interface and its options. -.. option:: -version [], --version [], /V [] - - Show program name/version banner and exit. - - If a file is specified, the version is written into it. - |file| - .. option:: --help-full [] Print all help manuals and exit. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 02bdcaf..5f6927f 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -10,12 +10,24 @@ Synopsis .. parsed-literal:: - ctest [] - ctest --build-and-test - --build-generator [...] - [--build-options ...] [--test-command [...]] - ctest {-D | -M -T | -S