ExternalData: Re-order documentation

Put example usage just after the intro.  Put hash algos last.
Put variables right after functions since they both cover the
module API.

1 files changed, 97 insertions, 97 deletions

diff --git a/Modules/ExternalData.cmake b/Modules/ExternalData.cmake
index 20180aeb8c..313d27d6a1 100644
--- a/Modules/ExternalData.cmake
+++ b/Modules/ExternalData.cmake
@@ -26,6 +26,27 @@ 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
+^^^^^^^^^^^^^
+
+.. code-block:: cmake
+
+ include(ExternalData)
+ set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
+                                "file:////host/share/%(algo)/%(hash)"
+                                "http://data.org/%(algo)/%(hash)")
+ ExternalData_Add_Test(MyData
+   NAME MyTest
+   COMMAND MyExe DATA{MyInput.png}
+   )
+ ExternalData_Add_Target(MyData)
+
+When test ``MyTest`` runs the ``DATA{MyInput.png}`` argument will be
+replaced by the full path to a real instance of the data file
+``MyInput.png`` on disk.  If the source tree contains a content link
+such as ``MyInput.png.md5`` then the ``MyData`` target creates a real
+``MyInput.png`` in the build tree.
+
 Module Functions
 ^^^^^^^^^^^^^^^^
 
@@ -74,43 +95,76 @@ Module Functions
   in one of the paths specified in the ``ExternalData_OBJECT_STORES``
   variable.
 
-Hash Algorithms
-^^^^^^^^^^^^^^^
+Module Variables
+^^^^^^^^^^^^^^^^
 
-The following hash algorithms are supported::
+The following variables configure behavior.  They should be set before
+calling any of the functions provided by this module.
 
- %(algo)     <ext>     Description
- -------     -----     -----------
- MD5         .md5      Message-Digest Algorithm 5, RFC 1321
- SHA1        .sha1     US Secure Hash Algorithm 1, RFC 3174
- SHA224      .sha224   US Secure Hash Algorithms, RFC 4634
- SHA256      .sha256   US Secure Hash Algorithms, RFC 4634
- SHA384      .sha384   US Secure Hash Algorithms, RFC 4634
- SHA512      .sha512   US Secure Hash Algorithms, RFC 4634
+.. variable:: ExternalData_BINARY_ROOT
 
-Note that the hashes are used only for unique data identification and
-download verification.
+  The ``ExternalData_BINARY_ROOT`` variable may be set to the directory to
+  hold the real data files named by expanded ``DATA{}`` references.  The
+  default is ``CMAKE_BINARY_DIR``.  The directory layout will mirror that of
+  content links under ``ExternalData_SOURCE_ROOT``.
 
-Example Usage
-^^^^^^^^^^^^^
+.. variable:: ExternalData_LINK_CONTENT
 
-.. code-block:: cmake
+  The ``ExternalData_LINK_CONTENT`` variable may be set to the name of a
+  supported hash algorithm to enable automatic conversion of real data
+  files referenced by the ``DATA{}`` syntax into content links.  For each
+  such ``<file>`` a content link named ``<file><ext>`` is created.  The
+  original file is renamed to the form ``.ExternalData_<algo>_<hash>`` to
+  stage it for future transmission to one of the locations in the list
+  of URL templates (by means outside the scope of this module).  The
+  data fetch rule created for the content link will use the staged
+  object if it cannot be found using any URL template.
 
- include(ExternalData)
- set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
-                                "file:////host/share/%(algo)/%(hash)"
-                                "http://data.org/%(algo)/%(hash)")
- ExternalData_Add_Test(MyData
-   NAME MyTest
-   COMMAND MyExe DATA{MyInput.png}
-   )
- ExternalData_Add_Target(MyData)
+.. variable:: ExternalData_OBJECT_STORES
 
-When test ``MyTest`` runs the ``DATA{MyInput.png}`` argument will be
-replaced by the full path to a real instance of the data file
-``MyInput.png`` on disk.  If the source tree contains a content link
-such as ``MyInput.png.md5`` then the ``MyData`` target creates a real
-``MyInput.png`` in the build tree.
+  The ``ExternalData_OBJECT_STORES`` variable may be set to a list of local
+  directories that store objects using the layout ``<dir>/%(algo)/%(hash)``.
+  These directories will be searched first for a needed object.  If the
+  object is not available in any store then it will be fetched remotely
+  using the URL templates and added to the first local store listed.  If
+  no stores are specified the default is a location inside the build
+  tree.
+
+.. variable:: ExternalData_SERIES_PARSE
+              ExternalData_SERIES_PARSE_PREFIX
+              ExternalData_SERIES_PARSE_NUMBER
+              ExternalData_SERIES_PARSE_SUFFIX
+              ExternalData_SERIES_MATCH
+
+  See `Referencing File Series`_.
+
+.. variable:: ExternalData_SOURCE_ROOT
+
+  The ``ExternalData_SOURCE_ROOT`` variable may be set to the highest source
+  directory containing any path named by a ``DATA{}`` reference.  The
+  default is ``CMAKE_SOURCE_DIR``.  ``ExternalData_SOURCE_ROOT`` and
+  ``CMAKE_SOURCE_DIR`` must refer to directories within a single source
+  distribution (e.g.  they come together in one tarball).
+
+.. variable:: ExternalData_TIMEOUT_ABSOLUTE
+
+  The ``ExternalData_TIMEOUT_ABSOLUTE`` variable sets the download
+  absolute timeout, in seconds, with a default of ``300`` seconds.
+  Set to ``0`` to disable enforcement.
+
+.. variable:: ExternalData_TIMEOUT_INACTIVITY
+
+  The ``ExternalData_TIMEOUT_INACTIVITY`` variable sets the download
+  inactivity timeout, in seconds, with a default of ``60`` seconds.
+  Set to ``0`` to disable enforcement.
+
+.. variable:: ExternalData_URL_TEMPLATES
+
+  The ``ExternalData_URL_TEMPLATES`` may be set to provide a list of
+  of URL templates using the placeholders ``%(algo)`` and ``%(hash)``
+  in each template.  Data fetch rules try each URL template in order
+  by substituting the hash algorithm name for ``%(algo)`` and the hash
+  value for ``%(hash)``.
 
 Referencing File Series
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -171,76 +225,22 @@ directory on the command line and ensure that the directory contains
 files corresponding to every file or content link in the ``MyDataDir``
 source directory.
 
-Module Variables
-^^^^^^^^^^^^^^^^
-
-The following variables configure behavior.  They should be set before
-calling any of the functions provided by this module.
-
-.. variable:: ExternalData_URL_TEMPLATES
-
-  The ``ExternalData_URL_TEMPLATES`` may be set to provide a list of
-  of URL templates using the placeholders ``%(algo)`` and ``%(hash)``
-  in each template.  Data fetch rules try each URL template in order
-  by substituting the hash algorithm name for ``%(algo)`` and the hash
-  value for ``%(hash)``.
-
-.. variable:: ExternalData_LINK_CONTENT
-
-  The ``ExternalData_LINK_CONTENT`` variable may be set to the name of a
-  supported hash algorithm to enable automatic conversion of real data
-  files referenced by the ``DATA{}`` syntax into content links.  For each
-  such ``<file>`` a content link named ``<file><ext>`` is created.  The
-  original file is renamed to the form ``.ExternalData_<algo>_<hash>`` to
-  stage it for future transmission to one of the locations in the list
-  of URL templates (by means outside the scope of this module).  The
-  data fetch rule created for the content link will use the staged
-  object if it cannot be found using any URL template.
-
-.. variable:: ExternalData_OBJECT_STORES
-
-  The ``ExternalData_OBJECT_STORES`` variable may be set to a list of local
-  directories that store objects using the layout ``<dir>/%(algo)/%(hash)``.
-  These directories will be searched first for a needed object.  If the
-  object is not available in any store then it will be fetched remotely
-  using the URL templates and added to the first local store listed.  If
-  no stores are specified the default is a location inside the build
-  tree.
-
-.. variable:: ExternalData_SOURCE_ROOT
-
-  The ``ExternalData_SOURCE_ROOT`` variable may be set to the highest source
-  directory containing any path named by a ``DATA{}`` reference.  The
-  default is ``CMAKE_SOURCE_DIR``.  ``ExternalData_SOURCE_ROOT`` and
-  ``CMAKE_SOURCE_DIR`` must refer to directories within a single source
-  distribution (e.g.  they come together in one tarball).
-
-.. variable:: ExternalData_BINARY_ROOT
-
-  The ``ExternalData_BINARY_ROOT`` variable may be set to the directory to
-  hold the real data files named by expanded ``DATA{}`` references.  The
-  default is ``CMAKE_BINARY_DIR``.  The directory layout will mirror that of
-  content links under ``ExternalData_SOURCE_ROOT``.
-
-.. variable:: ExternalData_TIMEOUT_INACTIVITY
-
-  The ``ExternalData_TIMEOUT_INACTIVITY`` variable sets the download
-  inactivity timeout, in seconds, with a default of ``60`` seconds.
-  Set to ``0`` to disable enforcement.
-
-.. variable:: ExternalData_TIMEOUT_ABSOLUTE
+Hash Algorithms
+^^^^^^^^^^^^^^^
 
-  The ``ExternalData_TIMEOUT_ABSOLUTE`` variable sets the download
-  absolute timeout, in seconds, with a default of ``300`` seconds.
-  Set to ``0`` to disable enforcement.
+The following hash algorithms are supported::
 
-.. variable:: ExternalData_SERIES_PARSE
-              ExternalData_SERIES_PARSE_PREFIX
-              ExternalData_SERIES_PARSE_NUMBER
-              ExternalData_SERIES_PARSE_SUFFIX
-              ExternalData_SERIES_MATCH
+ %(algo)     <ext>     Description
+ -------     -----     -----------
+ MD5         .md5      Message-Digest Algorithm 5, RFC 1321
+ SHA1        .sha1     US Secure Hash Algorithm 1, RFC 3174
+ SHA224      .sha224   US Secure Hash Algorithms, RFC 4634
+ SHA256      .sha256   US Secure Hash Algorithms, RFC 4634
+ SHA384      .sha384   US Secure Hash Algorithms, RFC 4634
+ SHA512      .sha512   US Secure Hash Algorithms, RFC 4634
 
-  See `Referencing File Series`_.
+Note that the hashes are used only for unique data identification and
+download verification.
 #]=======================================================================]
 
 #=============================================================================