From 51c0e1407c1317e8084c72fabebb60fffcaac99d Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 4 May 2018 08:18:32 -0400 Subject: Help: Add Synopsis section to install, list, and string docs Summarize the command signatures in one block at the top of the documentation as is typical in Unix command-line tool manuals. Make the mode keywords links to the corresponding full signature and documentation. Issue: #17948 --- Help/command/install.rst | 42 +++++++++--------- Help/command/list.rst | 78 +++++++++++++++++++-------------- Help/command/string.rst | 111 +++++++++++++++++++++++++++-------------------- 3 files changed, 132 insertions(+), 99 deletions(-) diff --git a/Help/command/install.rst b/Help/command/install.rst index a81714f..6cea996 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -1,19 +1,19 @@ install ------- -.. only:: html - - .. contents:: - Specify rules to run at install time. -This command accepts several signatures: +Synopsis +^^^^^^^^ -* :ref:`install(TARGETS) ` -* :ref:`install(FILES|PROGRAMS) ` -* :ref:`install(DIRECTORY) ` -* :ref:`install(SCRIPT|CODE) ` -* :ref:`install(EXPORT|EXPORT_ANDROID_MK) ` +.. parsed-literal:: + + install(`TARGETS`_ ... [...]) + install({`FILES`_ | `PROGRAMS`_} ... DESTINATION [...]) + install(`DIRECTORY`_ ... DESTINATION [...]) + install(`SCRIPT`_ [...]) + install(`CODE`_ [...]) + install(`EXPORT`_ DESTINATION [...]) Introduction ^^^^^^^^^^^^ @@ -89,11 +89,11 @@ Command signatures that install files may print messages during installation. Use the :variable:`CMAKE_INSTALL_MESSAGE` variable to control which messages are printed. -.. _install-targets: - Installing Targets ^^^^^^^^^^^^^^^^^^ +.. _TARGETS: + :: install(TARGETS targets... [EXPORT ] @@ -284,11 +284,12 @@ The install destination given to the target install ``DESTINATION`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. -.. _install-files: - Installing Files ^^^^^^^^^^^^^^^^ +.. _FILES: +.. _PROGRAMS: + :: install( files... DESTINATION @@ -319,11 +320,11 @@ The install destination given to the files install ``DESTINATION`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. -.. _install-directory: - Installing Directories ^^^^^^^^^^^^^^^^^^^^^^ +.. _DIRECTORY: + :: install(DIRECTORY dirs... DESTINATION @@ -402,11 +403,12 @@ given to the directory install ``DESTINATION`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. -.. _install-script: - Custom Installation Logic ^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _CODE: +.. _SCRIPT: + :: install([[SCRIPT ] [CODE ]] @@ -425,11 +427,11 @@ example, the code will print a message during installation. -.. _install-export: - Installing Exports ^^^^^^^^^^^^^^^^^^ +.. _EXPORT: + :: install(EXPORT DESTINATION diff --git a/Help/command/list.rst b/Help/command/list.rst index 7eb83ad..589e572 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -1,11 +1,37 @@ list ---- -.. only:: html +List operations. - .. contents:: +Synopsis +^^^^^^^^ -List operations. +.. parsed-literal:: + + `Reading`_ + list(`LENGTH`_ ) + list(`GET`_ [ ...] ) + list(`JOIN`_ ) + list(`SUBLIST`_ ) + + `Search`_ + list(`FIND`_ ) + + `Modification`_ + list(`APPEND`_ [...]) + list(`FILTER`_ {INCLUDE | EXCLUDE} REGEX ) + list(`INSERT`_ [...]) + list(`REMOVE_ITEM`_ ...) + list(`REMOVE_AT`_ ...) + list(`REMOVE_DUPLICATES`_ ) + list(`TRANSFORM`_ [...]) + + `Ordering`_ + list(`REVERSE`_ ) + list(`SORT`_ ) + +Introduction +^^^^^^^^^^^^ The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``, ``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create @@ -36,8 +62,7 @@ scope. To propagate the results of these operations upwards, use Reading ^^^^^^^ -LENGTH -"""""" +.. _LENGTH: :: @@ -45,8 +70,7 @@ LENGTH Returns the list's length. -GET -""" +.. _GET: :: @@ -54,8 +78,7 @@ GET Returns the list of elements specified by indices from the list. -JOIN -"""" +.. _JOIN: :: @@ -65,8 +88,7 @@ Returns a string joining all list's elements using the glue string. To join multiple strings, which are not part of a list, use ``JOIN`` operator from :command:`string` command. -SUBLIST -""""""" +.. _SUBLIST: :: @@ -80,8 +102,7 @@ the remaining elements of the list starting at ```` will be returned. Search ^^^^^^ -FIND -"""" +.. _FIND: :: @@ -93,8 +114,7 @@ if it wasn't found. Modification ^^^^^^^^^^^^ -APPEND -"""""" +.. _APPEND: :: @@ -102,8 +122,7 @@ APPEND Appends elements to the list. -FILTER -"""""" +.. _FILTER: :: @@ -115,8 +134,7 @@ In ``REGEX`` mode, items will be matched against the given regular expression. For more information on regular expressions see also the :command:`string` command. -INSERT -"""""" +.. _INSERT: :: @@ -124,8 +142,7 @@ INSERT Inserts elements to the list to the specified location. -REMOVE_ITEM -""""""""""" +.. _REMOVE_ITEM: :: @@ -133,8 +150,7 @@ REMOVE_ITEM Removes the given items from the list. -REMOVE_AT -""""""""" +.. _REMOVE_AT: :: @@ -142,8 +158,7 @@ REMOVE_AT Removes items at given indices from the list. -REMOVE_DUPLICATES -""""""""""""""""" +.. _REMOVE_DUPLICATES: :: @@ -151,8 +166,7 @@ REMOVE_DUPLICATES Removes duplicated items in the list. -TRANSFORM -""""""""" +.. _TRANSFORM: :: @@ -224,11 +238,10 @@ expression will be transformed. :: list(TRANSFORM REGEX ...) -Sorting -^^^^^^^ +Ordering +^^^^^^^^ -REVERSE -""""""" +.. _REVERSE: :: @@ -236,8 +249,7 @@ REVERSE Reverses the contents of the list in-place. -SORT -"""" +.. _SORT: :: diff --git a/Help/command/string.rst b/Help/command/string.rst index e84f788..efa923b 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -1,17 +1,52 @@ string ------ -.. only:: html - - .. contents:: - String operations. +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Search and Replace`_ + string(`FIND`_ [...]) + string(`REPLACE`_ ...) + + `Regular Expressions`_ + string(`REGEX MATCH`_ ...) + string(`REGEX MATCHALL`_ ...) + string(`REGEX REPLACE`_ ...) + + `Manipulation`_ + string(`APPEND`_ [...]) + string(`PREPEND`_ [...]) + string(`CONCAT`_ [...]) + string(`JOIN`_ [...]) + string(`TOLOWER`_ ) + string(`TOUPPER`_ ) + string(`LENGTH`_ ) + string(`SUBSTRING`_ ) + string(`STRIP`_ ) + string(`GENEX_STRIP`_ ) + + `Comparison`_ + string(`COMPARE`_ ) + + `Hashing`_ + string(`\ `_ ) + + `Generation`_ + string(`ASCII`_ ... ) + string(`CONFIGURE`_ [...]) + string(`MAKE_C_IDENTIFIER`_ ) + string(`RANDOM`_ [