instrumentation: Clarify API and Data version distinction

The instrumentation docs were unclear about the difference between API
and Data version, with the hierarchy of the table of contents being
particularly misleading.

Rework `cmake-instrumentation` manual and `cmake_instrumentation` command
documentation to be more clear.

Help/command/cmake_instrumentation.rst

@@ -20,9 +20,9 @@ This allows for configuring instrumentation at the project-level.
   )
 
 The ``API_VERSION`` and ``DATA_VERSION`` must always be given.  Currently, the
-only supported value for both fields is 1.  See :ref:`cmake-instrumentation API v1`
-for details of the ``API_VERSION`` and :ref:`cmake-instrumentation Data v1` for details
-of the ``DATA_VERSION``.
+only supported value for both fields is 1.  See
+:ref:`cmake-instrumentation API v1` for details of the ``API_VERSION`` and
+:ref:`cmake-instrumentation Data Version` for details of the ``DATA_VERSION``.
 
 Each of the optional keywords ``HOOKS``, ``OPTIONS``, and ``CALLBACK``
 correspond to one of the parameters to the :ref:`cmake-instrumentation v1 Query Files`.

Help/manual/cmake-instrumentation.7.rst

@@ -18,7 +18,7 @@ build, test and install steps for a CMake project.
 
 All interactions with the CMake instrumentation API must specify both an API
 version and a Data version. At this time, there is only one version for each of
-these: the `API v1`_ and `Data v1`_.
+these: see the `API v1`_ and `Data Version`_.
 
 .. note::
 
@@ -139,21 +139,21 @@ environment variable. Doing so automatically enables the
 The following table shows how each type of instrumented command gets mapped
 to a corresponding type of CTest XML file.
 
-=================================================== ==================
-:ref:`Snippet Role <cmake-instrumentation Data v1>` CTest XML File
-=================================================== ==================
-``configure``                                       ``Configure.xml``
-``generate``                                        ``Configure.xml``
-``compile``                                         ``Build.xml``
-``link``                                            ``Build.xml``
-``custom``                                          ``Build.xml``
-``build``                                           unused!
-``cmakeBuild``                                      ``Build.xml``
-``cmakeInstall``                                    ``Build.xml``
-``install``                                         ``Build.xml``
-``ctest``                                           ``Build.xml``
-``test``                                            ``Test.xml``
-=================================================== ==================
+=========================================================== ==================
+:ref:`Snippet Role <cmake-instrumentation v1 Snippet File>` CTest XML File
+=========================================================== ==================
+``configure``                                               ``Configure.xml``
+``generate``                                                ``Configure.xml``
+``compile``                                                 ``Build.xml``
+``link``                                                    ``Build.xml``
+``custom``                                                  ``Build.xml``
+``build``                                                   unused!
+``cmakeBuild``                                              ``Build.xml``
+``cmakeInstall``                                            ``Build.xml``
+``install``                                                 ``Build.xml``
+``ctest``                                                   ``Build.xml``
+``test``                                                    ``Test.xml``
+=========================================================== ==================
 
 By default the command line reported to CDash is truncated at the first space.
 You can instead choose to report the full command line (including arguments)
@@ -216,6 +216,23 @@ subdirectories:
   Holds temporary files used internally to generate XML content to be submitted
   to CDash.
 
+.. _`cmake-instrumentation Data Version`:
+
+Data Version
+------------
+
+The data version specifies the contents of the output files generated by the
+`API v1`_ as part of the `Data Collection`_ and `Indexing`_ processes.
+
+`v1 Query Files`_, or a :command:`cmake_instrumentation` invocation, should
+request a specific Data Version, and `v1 Data Files`_ of the corresponding
+version will be generated and sent to the user `Callbacks`_ defined in that
+query.
+
+Currently, the only supported version is ``1``. A new version number will be
+created whenever previously included data is removed or reformatted such that
+scripts written to parse this data may become incompatible with the new format.
+
 .. _`cmake-instrumentation v1 Query Files`:
 
 v1 Query Files
@@ -228,7 +245,7 @@ These files must contain a JSON object with the following keys. The ``version``
 key is required, but all other fields are optional.
 
 ``version``
-  The Data version of snippet file to generate, an integer. Currently the only
+  The `Data Version`_ of snippet file to generate, an integer. Currently the only
   supported version is ``1``.
 
 ``callbacks``
@@ -338,20 +355,19 @@ tree. The instrumentation data will be present in the XML files submitted to
 CDash, but with truncated command strings because ``cdashVerbose`` was not
 enabled.
 
-.. _`cmake-instrumentation Data v1`:
+v1 Data Files
+-------------
 
-Data v1
-=======
-
-Data version specifies the contents of the output files generated by the CMake
-instrumentation API as part of the `Data Collection`_ and `Indexing`_. A new
-version number will be created whenever previously included data is removed or
-reformatted such that scripts written to parse this data may become
-incompatible with the new format. There are four types of data files generated:
+There are four types of data files generated as part of `API v1`_:
 the `v1 Snippet File`_, `v1 Index File`_, `v1 CMake Content File`_, and the
-`Google Trace File`_. When using the `API v1`_, these files live in
+`Google Trace File`_. These files live in
 ``<build>/.cmake/instrumentation/v1/data/`` under the project build tree.
 
+Note that the ``v1`` delineation of these files refers to the `API v1`_.
+The `Data Version`_ of these files is specified with a ``version`` field as
+part of the file contents.
+
+
 .. _`cmake-instrumentation v1 Snippet File`:
 
 v1 Snippet File
@@ -386,7 +402,7 @@ Snippet files have a filename with the syntax
 ``<role>-<hash>-<timestamp>.json`` and contain the following data:
 
   ``version``
-    The Data version of the snippet file, an integer. Currently the version is
+    The `Data Version`_ of the snippet file, an integer. Currently the version is
     always ``1``.
 
   ``command``
@@ -522,7 +538,7 @@ generated whenever `Indexing`_ occurs and deleted after any user-specified
 `Callbacks`_ are executed.
 
 ``version``
-  The Data version of the index file, an integer. Currently the version is
+  The `Data Version`_ of the index file, an integer. Currently the version is
   always ``1``.
 
 ``buildDir``