Convert format from plain text to RST. [ci skip]

1 files changed, 121 insertions, 109 deletions

diff --git a/SCons/Tool/MSCommon/README.rst b/SCons/Tool/MSCommon/README.rst
index 5b09b58..7050c81 100644
--- a/SCons/Tool/MSCommon/README.rst
+++ b/SCons/Tool/MSCommon/README.rst
@@ -1,112 +1,124 @@
-####################################################################################
-# WARNING: The compiler detection logic documentation below is likely out-of-date. #
-#          The content of this file is transitioning to README.rst.                #
-####################################################################################
-
-This is the flow of the compiler detection logic:
-
-External to MSCommon:
-
-  The Tool init modules, in their exists() routines, call -> msvc_exists(env)
-
-At the moment, those modules are:
-  SCons/Tool/midl.py
-  SCons/Tool/mslib.py
-  SCons/Tool/mslink.py
-  SCons/Tool/msvc.py
-  SCons/Tool/msvs.py
-
-env may contain a version request in MSVC_VERSION, but this is not used
-in the detection that follows from msvc_exists(), only in the later
-batch that starts with a call to msvc_setup_env().
-
-Internal to MSCommon/vc.py:
-
-+ MSCommon/vc.py:msvc_exists:
-| vcs = cached_get_installed_vcs(env)
-| returns True if vcs > 0
-|
-+-> MSCommon/vc.py:cached_get_installed_vcs:
-  | checks global if we've run previously, if so return it
-  | populate the global from -> get_installed_vcs(env)
-  |
-  +-> MSCommon/vc.py:get_installed_vcs:
-    | loop through "known" versions of msvc, granularity is maj.min
-    |   check for product dir -> find_vc_pdir(env, ver)
+README - SCons.Tool.MSCommon 
+############################
+
+Compiler Detection Logic
+========================
+
+**WARNING: the compiler detection logic documentation below is likely out-of-date.**
+
+The verbatim content below is taken in its entirety from the existing ``MSCommom/README``
+file.
+
+In the future, the compiler detection logic documentation will be updated and integrated
+into the current document format as appropriate.
+
+::
+
+    This is the flow of the compiler detection logic:
+
+    External to MSCommon:
+
+      The Tool init modules, in their exists() routines, call -> msvc_exists(env)
+
+    At the moment, those modules are:
+      SCons/Tool/midl.py
+      SCons/Tool/mslib.py
+      SCons/Tool/mslink.py
+      SCons/Tool/msvc.py
+      SCons/Tool/msvs.py
+
+    env may contain a version request in MSVC_VERSION, but this is not used
+    in the detection that follows from msvc_exists(), only in the later
+    batch that starts with a call to msvc_setup_env().
+
+    Internal to MSCommon/vc.py:
+
+    + MSCommon/vc.py:msvc_exists:
+    | vcs = cached_get_installed_vcs(env)
+    | returns True if vcs > 0
     |
-    +-> MSCommon/vc.py:find_vc_pdir:
-      | From the msvc-version to pdir mapping dict, get reg key base and value
-      | If value is none -> find_vc_pdir_vswhere(ver, env)
+    +-> MSCommon/vc.py:cached_get_installed_vcs:
+      | checks global if we've run previously, if so return it
+      | populate the global from -> get_installed_vcs(env)
       |
-      +-> MSCommon/vc.py:find_vc_pdir_vswhere:
-        | From the vc-version to VS-version mapping table get string
-        | Figure out where vswhere is -> msvc_find_vswhere()
-        | Use subprocess to call vswhere, return first line of match
-        /
-      | else get product directory from registry (<= 14.0)
-      /
-    | if we found one -> _check_cl_exists_in_vc_dir(env, pdir, ver)
-    |
-    +-> MSCommon/vc.py:_check_cl_exists_in_vc_dir:
-      | Figure out host/target pair
-      | if version > 14.0 get specific version by looking in
-      |    pdir + Auxiliary/Build/Microsoft/VCToolsVersion/default.txt
-      |    look for pdir + Tools/MSVC/{specver}/bin/host/target/cl.exe
-      | if 14.0 or less, "do older stuff"
-
-All of this just got us a yes-no answer on whether /some/ msvc version
-exists, but does populate __INSTALLED_VCS_RUN with all of the top-level
-versions as noted for get_installed_vcs
-
-Externally:
-
-  Once a module's exists() has been called (or, in the case of
-  clang/clangxx, after the compiler has been detected by other means -
-  those still expect the rest of the msvc chain but not cl.exe)
-  the module's generate() function calls -> msvc_setup_env_once(env)
-
-Internally:
-
-+ MSCommon/vc.py:msvc_setup_env_once:
-| checks for environment flag MSVC_SETUP_RUN
-| if not, -> msvc_setup_env(env) and set flag
-|
-+-+ MSCommon/vc.py:msvc_setup_env:
-  | set ver from -> get_default_version(env)
-  |
-  +-+ MSCommon/vc.py:get_default_version:
-    | if no version specified in env.MSVC_VERSION:
-    |   return first entry from -> cached_get_installed_vcs(env)
-    | else return requested version
-    /
-  | get script from MSVC_USE_SCRIPT if set to a filename
-  | -> script_env(script)
-  |
-  +-+ MSCommon/vc.py:script_env:
-    | return (possibly cached) script variables matching script arg
-    /
-  | else -> msvc_find_valid_batch_script(env, version)
-  |
-  +-+ MSCommon/vc.py:msvc_find_valid_batch_script:
-    | Build a list of plausible target values, and loop through
-    |   look for host + target -> find_batch_file(env, ver, host, target)
+      +-> MSCommon/vc.py:get_installed_vcs:
+        | loop through "known" versions of msvc, granularity is maj.min
+        |   check for product dir -> find_vc_pdir(env, ver)
+        |
+        +-> MSCommon/vc.py:find_vc_pdir:
+          | From the msvc-version to pdir mapping dict, get reg key base and value
+          | If value is none -> find_vc_pdir_vswhere(ver, env)
+          |
+          +-> MSCommon/vc.py:find_vc_pdir_vswhere:
+            | From the vc-version to VS-version mapping table get string
+            | Figure out where vswhere is -> msvc_find_vswhere()
+            | Use subprocess to call vswhere, return first line of match
+            /
+          | else get product directory from registry (<= 14.0)
+          /
+        | if we found one -> _check_cl_exists_in_vc_dir(env, pdir, ver)
+        |
+        +-> MSCommon/vc.py:_check_cl_exists_in_vc_dir:
+          | Figure out host/target pair
+          | if version > 14.0 get specific version by looking in
+          |    pdir + Auxiliary/Build/Microsoft/VCToolsVersion/default.txt
+          |    look for pdir + Tools/MSVC/{specver}/bin/host/target/cl.exe
+          | if 14.0 or less, "do older stuff"
+
+    All of this just got us a yes-no answer on whether /some/ msvc version
+    exists, but does populate __INSTALLED_VCS_RUN with all of the top-level
+    versions as noted for get_installed_vcs
+
+    Externally:
+
+      Once a module's exists() has been called (or, in the case of
+      clang/clangxx, after the compiler has been detected by other means -
+      those still expect the rest of the msvc chain but not cl.exe)
+      the module's generate() function calls -> msvc_setup_env_once(env)
+
+    Internally:
+
+    + MSCommon/vc.py:msvc_setup_env_once:
+    | checks for environment flag MSVC_SETUP_RUN
+    | if not, -> msvc_setup_env(env) and set flag
     |
-    +-+ MSCommon/vc.py:find_batch_file:
-      | call -> find_vc_pdir (see above)
-      | use the return to construct a version-biased batfile path, check
-      /
-    | if not found, try sdk scripts (unknown if this is still useful)
-
-
-Problems:
-- For VS >= 2017, VS and VS are not 1:1, there can be many VC for one VS
-- For vswhere-ready versions, detection does not proceed beyond the
-  product level ("2019") into individual "features" (individual msvc)
-- As documented for MSVC_VERSION, compilers can only be requested if versions
-  are from the set in _VCVER, so 14.1 but not 14.16 or 14.16.27023
-- Information found in the first pass (msvs_exists) isn't really
-  available anywhere except the cached version list, since we just
-  return true/false.
-- Since msvc_exists chain of calls does not look at version, we
-  can proceed to compiler setup if *any* msvc was found, even if the
-  one requested wasn't found.
+    +-+ MSCommon/vc.py:msvc_setup_env:
+      | set ver from -> get_default_version(env)
+      |
+      +-+ MSCommon/vc.py:get_default_version:
+        | if no version specified in env.MSVC_VERSION:
+        |   return first entry from -> cached_get_installed_vcs(env)
+        | else return requested version
+        /
+      | get script from MSVC_USE_SCRIPT if set to a filename
+      | -> script_env(script)
+      |
+      +-+ MSCommon/vc.py:script_env:
+        | return (possibly cached) script variables matching script arg
+        /
+      | else -> msvc_find_valid_batch_script(env, version)
+      |
+      +-+ MSCommon/vc.py:msvc_find_valid_batch_script:
+        | Build a list of plausible target values, and loop through
+        |   look for host + target -> find_batch_file(env, ver, host, target)
+        |
+        +-+ MSCommon/vc.py:find_batch_file:
+          | call -> find_vc_pdir (see above)
+          | use the return to construct a version-biased batfile path, check
+          /
+        | if not found, try sdk scripts (unknown if this is still useful)
+
+
+    Problems:
+    - For VS >= 2017, VS and VS are not 1:1, there can be many VC for one VS
+    - For vswhere-ready versions, detection does not proceed beyond the
+      product level ("2019") into individual "features" (individual msvc)
+    - As documented for MSVC_VERSION, compilers can only be requested if versions
+      are from the set in _VCVER, so 14.1 but not 14.16 or 14.16.27023
+    - Information found in the first pass (msvs_exists) isn't really
+      available anywhere except the cached version list, since we just
+      return true/false.
+    - Since msvc_exists chain of calls does not look at version, we
+      can proceed to compiler setup if *any* msvc was found, even if the
+      one requested wasn't found.
+