From 7d918b3cee64961a1ed5e9c5a28f29cf0e48c130 Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 3 May 2018 14:48:58 -0400 Subject: cmRST: Parse inline links and inline literals Render links as the link text only. Render literals as themselves. This is closer to what the Sphinx text generator does. --- Source/cmRST.cxx | 68 ++++++++++++++++++++++++++++++++++++------- Source/cmRST.h | 2 ++ Tests/CMakeLib/testRST.expect | 4 +++ Tests/CMakeLib/testRST.rst | 4 +++ 4 files changed, 67 insertions(+), 11 deletions(-) diff --git a/Source/cmRST.cxx b/Source/cmRST.cxx index edcbc22..d9e5bcb 100644 --- a/Source/cmRST.cxx +++ b/Source/cmRST.cxx @@ -39,6 +39,8 @@ cmRST::cmRST(std::ostream& os, std::string const& docroot) "prop_test|prop_tgt|" "manual" "):`(<*([^`<]|[^` \t]<)*)([ \t]+<[^`]*>)?`") + , InlineLink("`(<*([^`<]|[^` \t]<)*)([ \t]+<[^`]*>)?`_") + , InlineLiteral("``([^`]*)``") , Substitution("(^|[^A-Za-z0-9_])" "((\\|[^| \t\r\n]([^|\r\n]*[^| \t\r\n])?\\|)(__|_|))" "([^A-Za-z0-9_]|$)") @@ -245,18 +247,62 @@ void cmRST::OutputLine(std::string const& line_in, bool inlineMarkup) if (inlineMarkup) { std::string line = this->ReplaceSubstitutions(line_in); std::string::size_type pos = 0; - while (this->CMakeRole.find(line.c_str() + pos)) { - this->OS << line.substr(pos, this->CMakeRole.start()); - std::string text = this->CMakeRole.match(3); - // If a command reference has no explicit target and - // no explicit "(...)" then add "()" to the text. - if (this->CMakeRole.match(2) == "command" && - this->CMakeRole.match(5).empty() && - text.find_first_of("()") == std::string::npos) { - text += "()"; + for (;;) { + std::string::size_type* first = nullptr; + std::string::size_type role_start = std::string::npos; + std::string::size_type link_start = std::string::npos; + std::string::size_type lit_start = std::string::npos; + if (this->CMakeRole.find(line.c_str() + pos)) { + role_start = this->CMakeRole.start(); + first = &role_start; + } + if (this->InlineLiteral.find(line.c_str() + pos)) { + lit_start = this->InlineLiteral.start(); + if (!first || lit_start < *first) { + first = &lit_start; + } + } + if (this->InlineLink.find(line.c_str() + pos)) { + link_start = this->InlineLink.start(); + if (!first || link_start < *first) { + first = &link_start; + } + } + if (first == &role_start) { + this->OS << line.substr(pos, role_start); + std::string text = this->CMakeRole.match(3); + // If a command reference has no explicit target and + // no explicit "(...)" then add "()" to the text. + if (this->CMakeRole.match(2) == "command" && + this->CMakeRole.match(5).empty() && + text.find_first_of("()") == std::string::npos) { + text += "()"; + } + this->OS << "``" << text << "``"; + pos += this->CMakeRole.end(); + } else if (first == &lit_start) { + this->OS << line.substr(pos, lit_start); + std::string text = this->InlineLiteral.match(1); + pos += this->InlineLiteral.end(); + this->OS << "``" << text << "``"; + } else if (first == &link_start) { + this->OS << line.substr(pos, link_start); + std::string text = this->InlineLink.match(1); + bool escaped = false; + for (char c : text) { + if (escaped) { + escaped = false; + this->OS << c; + } else if (c == '\\') { + escaped = true; + } else { + this->OS << c; + } + } + pos += this->InlineLink.end(); + } else { + break; } - this->OS << "``" << text << "``"; - pos += this->CMakeRole.end(); } this->OS << line.substr(pos) << "\n"; } else { diff --git a/Source/cmRST.h b/Source/cmRST.h index d1a8e27..ee47867 100644 --- a/Source/cmRST.h +++ b/Source/cmRST.h @@ -85,6 +85,8 @@ private: cmsys::RegularExpression NoteDirective; cmsys::RegularExpression ModuleRST; cmsys::RegularExpression CMakeRole; + cmsys::RegularExpression InlineLink; + cmsys::RegularExpression InlineLiteral; cmsys::RegularExpression Substitution; cmsys::RegularExpression TocTreeLink; diff --git a/Tests/CMakeLib/testRST.expect b/Tests/CMakeLib/testRST.expect index 4b29762..1ffd6b9 100644 --- a/Tests/CMakeLib/testRST.expect +++ b/Tests/CMakeLib/testRST.expect @@ -19,6 +19,10 @@ Variable ``VARIABLE_`` with trailing placeholder and target. Environment variable ``SOME_ENV_VAR``. Environment variable ``some env var`` with space and target. Generator ``Some Generator`` with space. +Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``. +Inline link Link Text. +Inline link Link Text . +Inline literal ``__`` followed by inline link Link Text. First TOC entry. diff --git a/Tests/CMakeLib/testRST.rst b/Tests/CMakeLib/testRST.rst index 9cd7257..c8587c0 100644 --- a/Tests/CMakeLib/testRST.rst +++ b/Tests/CMakeLib/testRST.rst @@ -26,6 +26,10 @@ Variable :variable:`VARIABLE_ ` with trailing placeholder a Environment variable :envvar:`SOME_ENV_VAR`. Environment variable :envvar:`some env var ` with space and target. Generator :generator:`Some Generator` with space. +Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``. +Inline link `Link Text `_. +Inline link `Link Text \ `_. +Inline literal ``__`` followed by inline link `Link Text `_. .. |not replaced| replace:: not replaced through toctree .. |not replaced in literal| replace:: replaced in parsed literal -- cgit v0.12 From d5b2745b34cba326a634bee677bb80c79ada52d9 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 4 May 2018 09:10:32 -0400 Subject: Help: Re-order file command docs Prepare for the addition of section headers for grouping commands. --- Help/command/file.rst | 250 +++++++++++++++++++++++++------------------------- 1 file changed, 125 insertions(+), 125 deletions(-) diff --git a/Help/command/file.rst b/Help/command/file.rst index 43ce3d9..518ba9d 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -7,22 +7,6 @@ File manipulation command. :: - file(WRITE ...) - file(APPEND ...) - -Write ```` into a file called ````. If the file does -not exist, it will be created. If the file already exists, ``WRITE`` -mode will overwrite it and ``APPEND`` mode will append to the end. -Any directories in the path specified by ```` that do not -exist will be created. - -If the file is a build input, use the :command:`configure_file` command -to update the file only when its content changes. - ------------------------------------------------------------------------------- - -:: - file(READ [OFFSET ] [LIMIT ] [HEX]) @@ -97,6 +81,98 @@ command. :: + file(TIMESTAMP [] [UTC]) + +Compute a string representation of the modification time of ```` +and store it in ````. Should the command be unable to obtain a +timestamp variable will be set to the empty string (""). + +See the :command:`string(TIMESTAMP)` command for documentation of +the ```` and ``UTC`` options. + +------------------------------------------------------------------------------ + +:: + + file(WRITE ...) + file(APPEND ...) + +Write ```` into a file called ````. If the file does +not exist, it will be created. If the file already exists, ``WRITE`` +mode will overwrite it and ``APPEND`` mode will append to the end. +Any directories in the path specified by ```` that do not +exist will be created. + +If the file is a build input, use the :command:`configure_file` command +to update the file only when its content changes. + +------------------------------------------------------------------------------ + +:: + + file(TOUCH [...]) + file(TOUCH_NOCREATE [...]) + +Create a file with no content if it does not yet exist. If the file already +exists, its access and/or modification will be updated to the time when the +function call is executed. + +Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file +does not exist it will be silently ignored. + +With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be +modified. + +------------------------------------------------------------------------------ + +:: + + file(GENERATE OUTPUT output-file + + [CONDITION expression]) + +Generate an output file for each build configuration supported by the current +:manual:`CMake Generator `. Evaluate +:manual:`generator expressions ` +from the input content to produce the output content. The options are: + +``CONDITION `` + Generate the output file for a particular configuration only if + the condition is true. The condition must be either ``0`` or ``1`` + after evaluating generator expressions. + +``CONTENT `` + Use the content given explicitly as input. + +``INPUT `` + Use the content from a given file as input. + A relative path is treated with respect to the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. + +``OUTPUT `` + Specify the output file name to generate. Use generator expressions + such as ``$`` to specify a configuration-specific output file + name. Multiple configurations may generate the same output file only + if the generated content is identical. Otherwise, the ```` + must evaluate to an unique name for each configuration. + A relative path (after evaluating generator expressions) is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0070`. + +Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific +``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. +Generated files are modified and their timestamp updated on subsequent cmake +runs only if their content is changed. + +Note also that ``file(GENERATE)`` does not create the output file until the +generation phase. The output file will not yet have been written when the +``file(GENERATE)`` command returns, it is written only after processing all +of a project's ``CMakeLists.txt`` files. + +------------------------------------------------------------------------------ + +:: + file(GLOB [LIST_DIRECTORIES true|false] [RELATIVE ] [CONFIGURE_DEPENDS] [...]) @@ -180,6 +256,39 @@ Create the given directories and their parents as needed. :: + file( ... DESTINATION + [FILE_PERMISSIONS ...] + [DIRECTORY_PERMISSIONS ...] + [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] + [FILES_MATCHING] + [[PATTERN | REGEX ] + [EXCLUDE] [PERMISSIONS ...]] [...]) + +The ``COPY`` signature copies files, directories, and symlinks to a +destination folder. Relative input paths are evaluated with respect +to the current source directory, and a relative destination is +evaluated with respect to the current build directory. Copying +preserves input file timestamps, and optimizes out a file if it exists +at the destination with the same timestamp. Copying preserves input +permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` +are given (default is ``USE_SOURCE_PERMISSIONS``). + +See the :command:`install(DIRECTORY)` command for documentation of +permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and +``EXCLUDE`` options. Copying directories preserves the structure +of their content even if options are used to select a subset of +files. + +The ``INSTALL`` signature differs slightly from ``COPY``: it prints +status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), +and ``NO_SOURCE_PERMISSIONS`` is default. +Installation scripts generated by the :command:`install` command +use this signature (with some undocumented options for internal use). + +------------------------------------------------------------------------------ + +:: + file(RELATIVE_PATH ) Compute the relative path from a ```` to a ```` and @@ -294,115 +403,6 @@ If neither ``TLS`` option is given CMake will check variables :: - file(TOUCH [...]) - file(TOUCH_NOCREATE [...]) - -Create a file with no content if it does not yet exist. If the file already -exists, its access and/or modification will be updated to the time when the -function call is executed. - -Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file -does not exist it will be silently ignored. - -With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be -modified. - ------------------------------------------------------------------------------- - -:: - - file(TIMESTAMP [] [UTC]) - -Compute a string representation of the modification time of ```` -and store it in ````. Should the command be unable to obtain a -timestamp variable will be set to the empty string (""). - -See the :command:`string(TIMESTAMP)` command for documentation of -the ```` and ``UTC`` options. - ------------------------------------------------------------------------------- - -:: - - file(GENERATE OUTPUT output-file - - [CONDITION expression]) - -Generate an output file for each build configuration supported by the current -:manual:`CMake Generator `. Evaluate -:manual:`generator expressions ` -from the input content to produce the output content. The options are: - -``CONDITION `` - Generate the output file for a particular configuration only if - the condition is true. The condition must be either ``0`` or ``1`` - after evaluating generator expressions. - -``CONTENT `` - Use the content given explicitly as input. - -``INPUT `` - Use the content from a given file as input. - A relative path is treated with respect to the value of - :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. - -``OUTPUT `` - Specify the output file name to generate. Use generator expressions - such as ``$`` to specify a configuration-specific output file - name. Multiple configurations may generate the same output file only - if the generated content is identical. Otherwise, the ```` - must evaluate to an unique name for each configuration. - A relative path (after evaluating generator expressions) is treated - with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. - See policy :policy:`CMP0070`. - -Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific -``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. -Generated files are modified and their timestamp updated on subsequent cmake -runs only if their content is changed. - -Note also that ``file(GENERATE)`` does not create the output file until the -generation phase. The output file will not yet have been written when the -``file(GENERATE)`` command returns, it is written only after processing all -of a project's ``CMakeLists.txt`` files. - ------------------------------------------------------------------------------- - -:: - - file( ... DESTINATION - [FILE_PERMISSIONS ...] - [DIRECTORY_PERMISSIONS ...] - [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] - [FILES_MATCHING] - [[PATTERN | REGEX ] - [EXCLUDE] [PERMISSIONS ...]] [...]) - -The ``COPY`` signature copies files, directories, and symlinks to a -destination folder. Relative input paths are evaluated with respect -to the current source directory, and a relative destination is -evaluated with respect to the current build directory. Copying -preserves input file timestamps, and optimizes out a file if it exists -at the destination with the same timestamp. Copying preserves input -permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` -are given (default is ``USE_SOURCE_PERMISSIONS``). - -See the :command:`install(DIRECTORY)` command for documentation of -permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and -``EXCLUDE`` options. Copying directories preserves the structure -of their content even if options are used to select a subset of -files. - -The ``INSTALL`` signature differs slightly from ``COPY``: it prints -status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), -and ``NO_SOURCE_PERMISSIONS`` is default. -Installation scripts generated by the :command:`install` command -use this signature (with some undocumented options for internal use). - ------------------------------------------------------------------------------- - -:: - file(LOCK [DIRECTORY] [RELEASE] [GUARD ] [RESULT_VARIABLE ] -- cgit v0.12 From 0acd70511946597b30e934369353654cdc18929e Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 7 May 2018 10:07:05 -0400 Subject: Help: Improve list command signature group name for read operations The LENGTH, GET, JOIN, and SUBLIST operations all read the list without modifying it. Name their section appropriately. --- Help/command/list.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Help/command/list.rst b/Help/command/list.rst index 67e9743..7eb83ad 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -33,8 +33,8 @@ scope. To propagate the results of these operations upwards, use Be careful when counting with negative indices: they do not start from 0. -0 is equivalent to 0, the first list element. -Capacity and Element access -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Reading +^^^^^^^ LENGTH """""" -- cgit v0.12 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`_ [