1 files changed, 17 insertions, 6 deletions
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index c406b76..e210e76 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -7191,7 +7191,7 @@ env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
 <refsect1 id='environment'><title>ENVIRONMENT</title>
 
 <para>In general, &scons; is not controlled by environment
-variables set shell used to invoke it, leaving it
+variables set in the shell used to invoke it, leaving it
 up to the SConscript file author to import those if desired.
 However the following variables are imported by
 &scons; itself if set:
@@ -7220,13 +7220,24 @@ in addition to those passed on the command line.</para>
     <listitem>
 <para>If set, save the shell environment variables generated
 in setting up the Microsoft Visual C++ compiler (and/or Build Tools),
-to give these settings (expensive to generate) persistence
-between runs of &scons;.
-If set to a True-like value (<literal>1</literal>,
-<literal>true</literal> or
-<literal>True</literal>) will cache to a file named
+to give these settings, which are expensive to generate, persistence
+across &scons; invocations.
+If set to a True-like value (<literal>"1"</literal>,
+<literal>"true"</literal> or
+<literal>"True"</literal>) will cache to a file named
 <filename>.scons_msvc_cache</filename> in the user's home directory.
 If set to a pathname, will use that pathname for the cache.</para>
+<para>
+Note: this behavior is not enabled by default because it
+might be somewhat fragile: while each major tool version
+(e.g. Visual Studio 2018 vs 2019) will get separate
+entries, if toolset updates cause a change
+to settings within a given release series, &scons; will not
+detect this and will fetch old settings.
+In case of problems, just remove the cache file.
+Use of this option is primarily intended to aid performance
+for tightly controlled Continuous Integration setups.
+</para>
     </listitem>
   </varlistentry>
 </variablelist>