Help: Document the $CACHE{} syntax

Also add a test case for the behavior.

2 files changed, 21 insertions, 3 deletions

diff --git a/Help/variable/CACHE.rst b/Help/variable/CACHE.rst
new file mode 100644
index 0000000..230739a
--- /dev/null
+++ b/Help/variable/CACHE.rst
@@ -0,0 +1,17 @@
+CACHE
+-----
+
+Read cache variables.
+
+Use the syntax ``$CACHE{VAR}`` to read cache entry ``VAR``.
+See the :ref:`cmake-language(7) variables <CMake Language Variables>`
+documentation for more complete documentation of the interaction of
+normal variables and cache entries.
+
+When evaluating :ref:`Variable References` of the form ``${VAR}``,
+CMake first searches for a normal variable with that name, and if not
+found CMake will search for a cache entry with that name.
+The ``$CACHE{VAR}`` syntax can be used to do direct cache lookup and
+ignore any existing normal variable.
+
+See the :command:`set` command to see how to write cache variables.
diff --git a/Help/variable/ENV.rst b/Help/variable/ENV.rst
index 368152a..98677dd 100644
--- a/Help/variable/ENV.rst
+++ b/Help/variable/ENV.rst
@@ -1,7 +1,8 @@
 ENV
 ---
 
-Access environment variables.
+Read environment variables.
 
-Use the syntax ``$ENV{VAR}`` to read environment variable ``VAR``.  See also
-the :command:`set` command to set ``ENV{VAR}``.
+Use the syntax ``$ENV{VAR}`` to read environment variable ``VAR``.
+
+See the :command:`set` command to see how to write environment variables.