summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBrad King <brad.king@kitware.com>2015-01-12 20:14:45 (GMT)
committerBrad King <brad.king@kitware.com>2015-01-15 15:48:09 (GMT)
commit945571db747fd09036d0efd55b538dd4b3c8b874 (patch)
tree48965649583eb9027b06da278ab3af0e3e1dede5
parenta32b2245ca8d77da5b8218bcdcc6958016cdbb48 (diff)
downloadCMake-945571db747fd09036d0efd55b538dd4b3c8b874.zip
CMake-945571db747fd09036d0efd55b538dd4b3c8b874.tar.gz
CMake-945571db747fd09036d0efd55b538dd4b3c8b874.tar.bz2
ExternalData: Improve documentation organization
Move the basic DATA{} description to a section just before the file series description. Move all sections on referencing files into subsections of a common "Referencing Files" section. Subsume example usage into the introduction since it gives a high-level starting point to understand the rest of the docs.
-rw-r--r--Modules/ExternalData.cmake31
1 files changed, 18 insertions, 13 deletions
diff --git a/Modules/ExternalData.cmake b/Modules/ExternalData.cmake
index 313d27d..4f84d53 100644
--- a/Modules/ExternalData.cmake
+++ b/Modules/ExternalData.cmake
@@ -18,16 +18,7 @@ recognize arguments with the syntax ``DATA{<name>}`` as references to
external data, replace them with full paths to local copies of those
data, and create build rules to fetch and update the local copies.
-The ``DATA{}`` syntax is literal and the ``<name>`` is a full or relative path
-within the source tree. The source tree must contain either a real
-data file at ``<name>`` or a "content link" at ``<name><ext>`` containing a
-hash of the real file using a hash algorithm corresponding to ``<ext>``.
-For example, the argument ``DATA{img.png}`` may be satisfied by either a
-real ``img.png`` file in the current source directory or a ``img.png.md5``
-file containing its MD5 sum.
-
-Example Usage
-^^^^^^^^^^^^^
+For example:
.. code-block:: cmake
@@ -166,8 +157,22 @@ calling any of the functions provided by this module.
by substituting the hash algorithm name for ``%(algo)`` and the hash
value for ``%(hash)``.
+Referencing Files
+^^^^^^^^^^^^^^^^^
+
+Referencing Single Files
+""""""""""""""""""""""""
+
+The ``DATA{}`` syntax is literal and the ``<name>`` is a full or relative path
+within the source tree. The source tree must contain either a real
+data file at ``<name>`` or a "content link" at ``<name><ext>`` containing a
+hash of the real file using a hash algorithm corresponding to ``<ext>``.
+For example, the argument ``DATA{img.png}`` may be satisfied by either a
+real ``img.png`` file in the current source directory or a ``img.png.md5``
+file containing its MD5 sum.
+
Referencing File Series
-^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""
The ``DATA{}`` syntax can be told to fetch a file series using the form
``DATA{<name>,:}``, where the ``:`` is literal. If the source tree
@@ -198,7 +203,7 @@ Note that the ``<suffix>`` of a series does not include a hash-algorithm
extension.
Referencing Associated Files
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""""
The ``DATA{}`` syntax can alternatively match files associated with the
named file and contained in the same directory. Associated files may
@@ -214,7 +219,7 @@ will pass ``MyInput.mha`` and ``MyFrames00.png`` on the command line but
ensure that the associated files are present next to them.
Referencing Directories
-^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""
The ``DATA{}`` syntax may reference a directory using a trailing slash and
a list of associated files. The form ``DATA{<name>/,<opt1>,<opt2>,...}``