[Cmake-commits] CMake branch, master, updated. v3.11.1-716-gdd3e1a7
Kitware Robot
kwrobot at kitware.com
Mon May 7 10:15:04 EDT 2018
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "CMake".
The branch, master has been updated
via dd3e1a737216b7c9bfb6c7569685b36a1bff9cba (commit)
via 72814e46dabe120964c9cebc55cc4952bf4837e3 (commit)
via 08b4ea639c877dee93d0a23a0fcf2ad41c7a1fcc (commit)
via 51c0e1407c1317e8084c72fabebb60fffcaac99d (commit)
via 0acd70511946597b30e934369353654cdc18929e (commit)
via d5b2745b34cba326a634bee677bb80c79ada52d9 (commit)
via 7d918b3cee64961a1ed5e9c5a28f29cf0e48c130 (commit)
from 42db369133d4cfc0e47bb624b2a08e57fee097a5 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=dd3e1a737216b7c9bfb6c7569685b36a1bff9cba
commit dd3e1a737216b7c9bfb6c7569685b36a1bff9cba
Merge: 42db369 72814e4
Author: Brad King <brad.king at kitware.com>
AuthorDate: Mon May 7 14:12:00 2018 +0000
Commit: Kitware Robot <kwrobot at kitware.com>
CommitDate: Mon May 7 10:12:05 2018 -0400
Merge topic 'doc-command-synopsis'
72814e46da Utilities/Sphinx: Make HTML links in parsed-literal blocks more obvious
08b4ea639c Help: Organize file command docs into sections
51c0e1407c Help: Add Synopsis section to install, list, and string docs
0acd705119 Help: Improve list command signature group name for read operations
d5b2745b34 Help: Re-order file command docs
7d918b3cee cmRST: Parse inline links and inline literals
Acked-by: Kitware Robot <kwrobot at kitware.com>
Merge-request: !2039
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=72814e46dabe120964c9cebc55cc4952bf4837e3
commit 72814e46dabe120964c9cebc55cc4952bf4837e3
Author: Brad King <brad.king at kitware.com>
AuthorDate: Fri May 4 13:26:32 2018 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Mon May 7 10:10:37 2018 -0400
Utilities/Sphinx: Make HTML links in parsed-literal blocks more obvious
Hyperlink text color does not stand out when used inside a literal block
because such blocks typically get syntax highlighting. Update our CSS
style to make the links more distinct.
Suggested-by: Kyle Edwards <kyle.edwards at kitware.com>
diff --git a/Utilities/Sphinx/static/cmake.css b/Utilities/Sphinx/static/cmake.css
index 2a326d4..b082ede 100644
--- a/Utilities/Sphinx/static/cmake.css
+++ b/Utilities/Sphinx/static/cmake.css
@@ -6,3 +6,13 @@
div.sphinxsidebarwrapper {
word-wrap: break-word;
}
+
+/* Make links inside parsed-literal blocks more obvious
+ by using a background color and increased line spacing
+ to make them look boxed. */
+.literal-block {
+ line-height: 1.4;
+}
+.literal-block a.reference.internal {
+ background-color: #dfdfdf;
+}
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=08b4ea639c877dee93d0a23a0fcf2ad41c7a1fcc
commit 08b4ea639c877dee93d0a23a0fcf2ad41c7a1fcc
Author: Brad King <brad.king at kitware.com>
AuthorDate: Fri May 4 09:12:07 2018 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Mon May 7 10:10:37 2018 -0400
Help: Organize file command docs into sections
Add a synopsis section at the top summarizing all signatures.
Issue: #17948
diff --git a/Help/command/file.rst b/Help/command/file.rst
index 518ba9d..d4a6006 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -3,7 +3,44 @@ file
File manipulation command.
-------------------------------------------------------------------------------
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+ `Reading`_
+ file(`READ`_ <filename> <out-var> [...])
+ file(`STRINGS`_ <filename> <out-var> [...])
+ file(`\<HASH\> <HASH_>`_ <filename> <out-var>)
+ file(`TIMESTAMP`_ <filename> <out-var> [...])
+
+ `Writing`_
+ file({`WRITE`_ | `APPEND`_} <filename> <content>...)
+ file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...])
+ file(`GENERATE`_ OUTPUT <output-file> [...])
+
+ `Filesystem`_
+ file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...])
+ file(`RENAME`_ <oldname> <newname>)
+ file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...])
+ file(`MAKE_DIRECTORY`_ [<dir>...])
+ file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...])
+
+ `Path Conversion`_
+ file(`RELATIVE_PATH`_ <out-var> <directory> <file>)
+ file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>)
+
+ `Transfer`_
+ file(`DOWNLOAD`_ <url> <file> [...])
+ file(`UPLOAD`_ <file> <url> [...])
+
+ `Locking`_
+ file(`LOCK`_ <path> [...])
+
+Reading
+^^^^^^^
+
+.. _READ:
::
@@ -15,7 +52,7 @@ Read content from a file called ``<filename>`` and store it in a
read at most ``<max-in>`` bytes. The ``HEX`` option causes data to
be converted to a hexadecimal representation (useful for binary data).
-------------------------------------------------------------------------------
+.. _STRINGS:
::
@@ -66,7 +103,7 @@ For example, the code
stores a list in the variable ``myfile`` in which each item is a line
from the input file.
-------------------------------------------------------------------------------
+.. _HASH:
::
@@ -77,7 +114,7 @@ store it in a ``<variable>``. The supported ``<HASH>`` algorithm names
are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>`
command.
-------------------------------------------------------------------------------
+.. _TIMESTAMP:
::
@@ -90,7 +127,11 @@ timestamp variable will be set to the empty string ("").
See the :command:`string(TIMESTAMP)` command for documentation of
the ``<format>`` and ``UTC`` options.
-------------------------------------------------------------------------------
+Writing
+^^^^^^^
+
+.. _WRITE:
+.. _APPEND:
::
@@ -106,7 +147,8 @@ 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.
-------------------------------------------------------------------------------
+.. _TOUCH:
+.. _TOUCH_NOCREATE:
::
@@ -123,7 +165,7 @@ does not exist it will be silently ignored.
With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be
modified.
-------------------------------------------------------------------------------
+.. _GENERATE:
::
@@ -169,7 +211,11 @@ 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.
-------------------------------------------------------------------------------
+Filesystem
+^^^^^^^^^^
+
+.. _GLOB:
+.. _GLOB_RECURSE:
::
@@ -224,7 +270,7 @@ Examples of recursive globbing include::
/dir/*.py - match all python files in /dir and subdirectories
-------------------------------------------------------------------------------
+.. _RENAME:
::
@@ -233,7 +279,8 @@ Examples of recursive globbing include::
Move a file or directory within a filesystem from ``<oldname>`` to
``<newname>``, replacing the destination atomically.
-------------------------------------------------------------------------------
+.. _REMOVE:
+.. _REMOVE_RECURSE:
::
@@ -244,7 +291,7 @@ Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given
files and directories, also non-empty directories. No error is emitted if a
given file does not exist.
-------------------------------------------------------------------------------
+.. _MAKE_DIRECTORY:
::
@@ -252,7 +299,8 @@ given file does not exist.
Create the given directories and their parents as needed.
-------------------------------------------------------------------------------
+.. _COPY:
+.. _INSTALL:
::
@@ -285,7 +333,10 @@ and ``NO_SOURCE_PERMISSIONS`` is default.
Installation scripts generated by the :command:`install` command
use this signature (with some undocumented options for internal use).
-------------------------------------------------------------------------------
+Path Conversion
+^^^^^^^^^^^^^^^
+
+.. _RELATIVE_PATH:
::
@@ -294,7 +345,8 @@ use this signature (with some undocumented options for internal use).
Compute the relative path from a ``<directory>`` to a ``<file>`` and
store it in the ``<variable>``.
-------------------------------------------------------------------------------
+.. _TO_CMAKE_PATH:
+.. _TO_NATIVE_PATH:
::
@@ -312,7 +364,11 @@ path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere).
Always use double quotes around the ``<path>`` to be sure it is treated
as a single argument to this command.
-------------------------------------------------------------------------------
+Transfer
+^^^^^^^^
+
+.. _DOWNLOAD:
+.. _UPLOAD:
::
@@ -399,7 +455,10 @@ check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content.
If neither ``TLS`` option is given CMake will check variables
``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.
-------------------------------------------------------------------------------
+Locking
+^^^^^^^
+
+.. _LOCK:
::
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=51c0e1407c1317e8084c72fabebb60fffcaac99d
commit 51c0e1407c1317e8084c72fabebb60fffcaac99d
Author: Brad King <brad.king at kitware.com>
AuthorDate: Fri May 4 08:18:32 2018 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Mon May 7 10:10:37 2018 -0400
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
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) <install-targets>`
-* :ref:`install(FILES|PROGRAMS) <install-files>`
-* :ref:`install(DIRECTORY) <install-directory>`
-* :ref:`install(SCRIPT|CODE) <install-script>`
-* :ref:`install(EXPORT|EXPORT_ANDROID_MK) <install-export>`
+.. parsed-literal::
+
+ install(`TARGETS`_ <target>... [...])
+ install({`FILES`_ | `PROGRAMS`_} <file>... DESTINATION <dir> [...])
+ install(`DIRECTORY`_ <dir>... DESTINATION <dir> [...])
+ install(`SCRIPT`_ <file> [...])
+ install(`CODE`_ <code> [...])
+ install(`EXPORT`_ <export-name> DESTINATION <dir> [...])
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 <export-name>]
@@ -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|PROGRAMS> files... DESTINATION <dir>
@@ -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 <dir>
@@ -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 <file>] [CODE <code>]]
@@ -425,11 +427,11 @@ example, the code
will print a message during installation.
-.. _install-export:
-
Installing Exports
^^^^^^^^^^^^^^^^^^
+.. _EXPORT:
+
::
install(EXPORT <export-name> DESTINATION <dir>
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> <out-var>)
+ list(`GET`_ <list> <element index> [<index> ...] <out-var>)
+ list(`JOIN`_ <list> <glue> <out-var>)
+ list(`SUBLIST`_ <list> <begin> <length> <out-var>)
+
+ `Search`_
+ list(`FIND`_ <list> <value> <out-var>)
+
+ `Modification`_
+ list(`APPEND`_ <list> [<element>...])
+ list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>)
+ list(`INSERT`_ <list> <index> [<element>...])
+ list(`REMOVE_ITEM`_ <list> <value>...)
+ list(`REMOVE_AT`_ <list> <index>...)
+ list(`REMOVE_DUPLICATES`_ <list>)
+ list(`TRANSFORM`_ <list> <ACTION> [...])
+
+ `Ordering`_
+ list(`REVERSE`_ <list>)
+ list(`SORT`_ <list>)
+
+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 ``<begin>`` 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 <list> <ACTION> REGEX <regular_expression> ...)
-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> <substring> <out-var> [...])
+ string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...)
+
+ `Regular Expressions`_
+ string(`REGEX MATCH`_ <match-regex> <out-var> <input>...)
+ string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...)
+ string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...)
+
+ `Manipulation`_
+ string(`APPEND`_ <string-var> [<input>...])
+ string(`PREPEND`_ <string-var> [<input>...])
+ string(`CONCAT`_ <out-var> [<input>...])
+ string(`JOIN`_ <glue> <out-var> [<input>...])
+ string(`TOLOWER`_ <string1> <out-var>)
+ string(`TOUPPER`_ <string1> <out-var>)
+ string(`LENGTH`_ <string> <out-var>)
+ string(`SUBSTRING`_ <string> <begin> <length> <out-var>)
+ string(`STRIP`_ <string> <out-var>)
+ string(`GENEX_STRIP`_ <string> <out-var>)
+
+ `Comparison`_
+ string(`COMPARE`_ <op> <string1> <string2> <out-var>)
+
+ `Hashing`_
+ string(`\<HASH\> <HASH_>`_ <out-var> <input>)
+
+ `Generation`_
+ string(`ASCII`_ <number>... <out-var>)
+ string(`CONFIGURE`_ <string1> <out-var> [...])
+ string(`MAKE_C_IDENTIFIER`_ <string> <out-var>)
+ string(`RANDOM`_ [<option>...] <out-var>)
+ string(`TIMESTAMP`_ <out-var> [<format string>] [UTC])
+ string(`UUID`_ <out-var> ...)
+
Search and Replace
^^^^^^^^^^^^^^^^^^
-FIND
-""""
+.. _FIND:
::
@@ -22,8 +57,7 @@ the supplied string. If the ``REVERSE`` flag was used, the command will
search for the position of the last occurrence of the specified
substring. If the substring is not found, a position of -1 is returned.
-REPLACE
-"""""""
+.. _REPLACE:
::
@@ -37,8 +71,7 @@ with ``replace_string`` and store the result in the output.
Regular Expressions
^^^^^^^^^^^^^^^^^^^
-REGEX MATCH
-"""""""""""
+.. _`REGEX MATCH`:
::
@@ -48,8 +81,7 @@ REGEX MATCH
Match the regular expression once and store the match in the output variable.
All ``<input>`` arguments are concatenated before matching.
-REGEX MATCHALL
-""""""""""""""
+.. _`REGEX MATCHALL`:
::
@@ -60,8 +92,7 @@ Match the regular expression as many times as possible and store the matches
in the output variable as a list.
All ``<input>`` arguments are concatenated before matching.
-REGEX REPLACE
-"""""""""""""
+.. _`REGEX REPLACE`:
::
@@ -123,8 +154,7 @@ expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``.
Manipulation
^^^^^^^^^^^^
-APPEND
-""""""
+.. _APPEND:
::
@@ -132,8 +162,7 @@ APPEND
Append all the input arguments to the string.
-PREPEND
-"""""""
+.. _PREPEND:
::
@@ -141,8 +170,7 @@ PREPEND
Prepend all the input arguments to the string.
-CONCAT
-""""""
+.. _CONCAT:
::
@@ -151,8 +179,7 @@ CONCAT
Concatenate all the input arguments together and store
the result in the named output variable.
-JOIN
-""""
+.. _JOIN:
::
@@ -165,8 +192,7 @@ To join list's elements, use preferably the ``JOIN`` operator
from :command:`list` command. This allows for the elements to have
special characters like ``;`` in them.
-TOLOWER
-"""""""
+.. _TOLOWER:
::
@@ -174,8 +200,7 @@ TOLOWER
Convert string to lower characters.
-TOUPPER
-"""""""
+.. _TOUPPER:
::
@@ -183,8 +208,7 @@ TOUPPER
Convert string to upper characters.
-LENGTH
-""""""
+.. _LENGTH:
::
@@ -192,8 +216,7 @@ LENGTH
Store in an output variable a given string's length.
-SUBSTRING
-"""""""""
+.. _SUBSTRING:
::
@@ -207,8 +230,7 @@ If string is shorter than length then end of string is used instead.
CMake 3.1 and below reported an error if length pointed past
the end of string.
-STRIP
-"""""
+.. _STRIP:
::
@@ -217,8 +239,7 @@ STRIP
Store in an output variable a substring of a given string with leading and
trailing spaces removed.
-GENEX_STRIP
-"""""""""""
+.. _GENEX_STRIP:
::
@@ -230,6 +251,8 @@ from the ``input string`` and store the result in the ``output variable``.
Comparison
^^^^^^^^^^
+.. _COMPARE:
+
::
string(COMPARE LESS <string1> <string2> <output variable>)
@@ -246,6 +269,8 @@ Compare the strings and store true or false in the output variable.
Hashing
^^^^^^^
+.. _`HASH`:
+
::
string(<HASH> <output variable> <input>)
@@ -277,8 +302,7 @@ The supported ``<HASH>`` algorithm names are:
Generation
^^^^^^^^^^
-ASCII
-"""""
+.. _ASCII:
::
@@ -286,8 +310,7 @@ ASCII
Convert all numbers into corresponding ASCII characters.
-CONFIGURE
-"""""""""
+.. _CONFIGURE:
::
@@ -296,8 +319,7 @@ CONFIGURE
Transform a string like :command:`configure_file` transforms a file.
-MAKE_C_IDENTIFIER
-"""""""""""""""""
+.. _MAKE_C_IDENTIFIER:
::
@@ -308,8 +330,7 @@ underscore and store the result in the ``<output variable>``. If the first
character of the string is a digit, an underscore will also be prepended to
the result.
-RANDOM
-""""""
+.. _RANDOM:
::
@@ -322,8 +343,7 @@ and default alphabet is all numbers and upper and lower case letters.
If an integer ``RANDOM_SEED`` is given, its value will be used to seed the
random number generator.
-TIMESTAMP
-"""""""""
+.. _TIMESTAMP:
::
@@ -378,8 +398,7 @@ If no explicit ``<format string>`` is given it will default to:
its value will be used instead of the current time.
See https://reproducible-builds.org/specs/source-date-epoch/ for details.
-UUID
-""""
+.. _UUID:
::
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=0acd70511946597b30e934369353654cdc18929e
commit 0acd70511946597b30e934369353654cdc18929e
Author: Brad King <brad.king at kitware.com>
AuthorDate: Mon May 7 10:07:05 2018 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Mon May 7 10:10:37 2018 -0400
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.
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
""""""
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=d5b2745b34cba326a634bee677bb80c79ada52d9
commit d5b2745b34cba326a634bee677bb80c79ada52d9
Author: Brad King <brad.king at kitware.com>
AuthorDate: Fri May 4 09:10:32 2018 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Mon May 7 10:10:37 2018 -0400
Help: Re-order file command docs
Prepare for the addition of section headers for grouping commands.
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 <filename> <content>...)
- file(APPEND <filename> <content>...)
-
-Write ``<content>`` into a file called ``<filename>``. 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 ``<filename>`` 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 <filename> <variable>
[OFFSET <offset>] [LIMIT <max-in>] [HEX])
@@ -97,6 +81,98 @@ command.
::
+ file(TIMESTAMP <filename> <variable> [<format>] [UTC])
+
+Compute a string representation of the modification time of ``<filename>``
+and store it in ``<variable>``. 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 ``<format>`` and ``UTC`` options.
+
+------------------------------------------------------------------------------
+
+::
+
+ file(WRITE <filename> <content>...)
+ file(APPEND <filename> <content>...)
+
+Write ``<content>`` into a file called ``<filename>``. 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 ``<filename>`` 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 [<files>...])
+ file(TOUCH_NOCREATE [<files>...])
+
+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
+ <INPUT input-file|CONTENT content>
+ [CONDITION expression])
+
+Generate an output file for each build configuration supported by the current
+:manual:`CMake Generator <cmake-generators(7)>`. Evaluate
+:manual:`generator expressions <cmake-generator-expressions(7)>`
+from the input content to produce the output content. The options are:
+
+``CONDITION <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 <content>``
+ Use the content given explicitly as input.
+
+``INPUT <input-file>``
+ 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 <output-file>``
+ Specify the output file name to generate. Use generator expressions
+ such as ``$<CONFIG>`` 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 ``<output-file>``
+ 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 <variable>
[LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
[<globbing-expressions>...])
@@ -180,6 +256,39 @@ Create the given directories and their parents as needed.
::
+ file(<COPY|INSTALL> <files>... DESTINATION <dir>
+ [FILE_PERMISSIONS <permissions>...]
+ [DIRECTORY_PERMISSIONS <permissions>...]
+ [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
+ [FILES_MATCHING]
+ [[PATTERN <pattern> | REGEX <regex>]
+ [EXCLUDE] [PERMISSIONS <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 <variable> <directory> <file>)
Compute the relative path from a ``<directory>`` to a ``<file>`` and
@@ -294,115 +403,6 @@ If neither ``TLS`` option is given CMake will check variables
::
- file(TOUCH [<files>...])
- file(TOUCH_NOCREATE [<files>...])
-
-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 <filename> <variable> [<format>] [UTC])
-
-Compute a string representation of the modification time of ``<filename>``
-and store it in ``<variable>``. 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 ``<format>`` and ``UTC`` options.
-
-------------------------------------------------------------------------------
-
-::
-
- file(GENERATE OUTPUT output-file
- <INPUT input-file|CONTENT content>
- [CONDITION expression])
-
-Generate an output file for each build configuration supported by the current
-:manual:`CMake Generator <cmake-generators(7)>`. Evaluate
-:manual:`generator expressions <cmake-generator-expressions(7)>`
-from the input content to produce the output content. The options are:
-
-``CONDITION <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 <content>``
- Use the content given explicitly as input.
-
-``INPUT <input-file>``
- 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 <output-file>``
- Specify the output file name to generate. Use generator expressions
- such as ``$<CONFIG>`` 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 ``<output-file>``
- 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(<COPY|INSTALL> <files>... DESTINATION <dir>
- [FILE_PERMISSIONS <permissions>...]
- [DIRECTORY_PERMISSIONS <permissions>...]
- [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
- [FILES_MATCHING]
- [[PATTERN <pattern> | REGEX <regex>]
- [EXCLUDE] [PERMISSIONS <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 <path> [DIRECTORY] [RELEASE]
[GUARD <FUNCTION|FILE|PROCESS>]
[RESULT_VARIABLE <variable>]
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=7d918b3cee64961a1ed5e9c5a28f29cf0e48c130
commit 7d918b3cee64961a1ed5e9c5a28f29cf0e48c130
Author: Brad King <brad.king at kitware.com>
AuthorDate: Thu May 3 14:48:58 2018 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Mon May 7 10:10:37 2018 -0400
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.
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_<PLACEHOLDER>`` 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 <With \-escaped Brackets>.
+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_<PLACEHOLDER> <target>` with trailing placeholder a
Environment variable :envvar:`SOME_ENV_VAR`.
Environment variable :envvar:`some env var <SOME_ENV_VAR>` with space and target.
Generator :generator:`Some Generator` with space.
+Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``.
+Inline link `Link Text <ExternalDest>`_.
+Inline link `Link Text \<With \\-escaped Brackets\> <ExternalDest>`_.
+Inline literal ``__`` followed by inline link `Link Text <InternalDest_>`_.
.. |not replaced| replace:: not replaced through toctree
.. |not replaced in literal| replace:: replaced in parsed literal
-----------------------------------------------------------------------
Summary of changes:
Help/command/file.rst | 319 ++++++++++++++++++++++---------------
Help/command/install.rst | 42 ++---
Help/command/list.rst | 82 ++++++----
Help/command/string.rst | 111 +++++++------
Source/cmRST.cxx | 68 ++++++--
Source/cmRST.h | 2 +
Tests/CMakeLib/testRST.expect | 4 +
Tests/CMakeLib/testRST.rst | 4 +
Utilities/Sphinx/static/cmake.css | 10 ++
9 files changed, 400 insertions(+), 242 deletions(-)
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list