Update and clarify filter documentation

Based on review feedback from @hadess

4 files changed, 109 insertions, 113 deletions

diff --git a/docs/LoaderDebugging.md b/docs/LoaderDebugging.md
index c8ebbc38e..b7fce45af 100644
--- a/docs/LoaderDebugging.md
+++ b/docs/LoaderDebugging.md
@@ -304,13 +304,13 @@ DRIVER:        Using "Intel(R) UHD Graphics 630 (CFL GT2)" with driver: "/usr/li
 1.3.yyyy of the Vulkan headers and later.
 
 You can now use the filtering environment variables
-(`VK_LOADER_DRIVERS_SELECT` and `VK_LOADER_DRIVERS_DISABLE`) to selectively
-select or disable various drivers.
-Remember, that to disable drivers, you must use the name of the Driver JSON to
-disable since the drivers do not reveal a name until much later in the Vulkan
-initialization process.
+(`VK_LOADER_DRIVERS_SELECT` and `VK_LOADER_DRIVERS_DISABLE`) to control what
+drivers the loader will attempt to load.
+For drivers, the string globs passed into the above environment variables will
+be compared against the driver JSON file name since there is no driver name
+known to the loader until much later in the Vulkan initialization process.
 
-So to disable all drivers except Nvidia you could do the following:
+For example, to disable all drivers except Nvidia you could do the following:
 
 ```
 set VK_LOADER_DRIVERS_DISABLE=*
@@ -325,9 +325,6 @@ WARNING | DRIVER: Driver "intel_icd.x86_64.json" ignored because not selected by
 WARNING | DRIVER: Driver "radeon_icd.x86_64.json" ignored because it was disabled by env var 'VK_LOADER_DRIVERS_DISABLE'
 ```
 
-These can be used to make sure that the appropriate drivers are enabled/disabled
-properly.
-
 For more info on how to use the filtering environment variables, refer to the
 [Driver Filtering](LoaderDriverInterface.md#driver-filtering) section of the
 [LoaderDriverInterface](LoaderDriverInterface.md) document.
diff --git a/docs/LoaderDriverInterface.md b/docs/LoaderDriverInterface.md
index 5fd146e3e..6e820e0a6 100644
--- a/docs/LoaderDriverInterface.md
+++ b/docs/LoaderDriverInterface.md
@@ -20,10 +20,8 @@
   - [Overriding the Default Driver Discovery](#overriding-the-default-driver-discovery)
   - [Additional Driver Discovery](#additional-driver-discovery)
   - [Driver Filtering](#driver-filtering)
-    - [Comma-delimited lists](#comma-delimited-lists)
-    - [Globs](#globs)
-    - [Case-insensitive](#case-insensitive)
-    - [Environment Variable Priority](#environment-variable-priority)
+    - [Driver Select Filtering](#driver-select-filtering)
+    - [Driver Disable Filtering](#driver-disable-filtering)
   - [Exception for Elevated Privileges](#exception-for-elevated-privileges)
     - [Examples](#examples)
       - [On Windows](#on-windows)
@@ -145,17 +143,26 @@ ignored.
 **NOTE:** This functionality is only available with Loaders built with version
 1.3.yyyy of the Vulkan headers and later.
 
-The driver select environment variable `VK_LOADER_DRIVERS_SELECT` is a
-comma-delimited list of globs to search for in known drivers.
-Since drivers don’t have a name like layers, this substring is used to compare
-against the manifest filename.
+The loader supports filter environment variables which can forcibly select and
+disable known drivers.
 Known driver manifests are those files that are already found by the loader
 taking into account default search paths and other environment variables (like
 `VK_ICD_FILENAMES` or `VK_ADD_DRIVER_FILES`).
 
-When a driver is disabled using the `VK_LOADER_DRIVERS_SELECT` filter, and
-loader logging is set to emit either warnings or driver messages, then a message
-will show for each driver that has been ignored.
+The filter variables will be compared against the driver's manifest filename.
+
+The filters must also follow the behaviors define in the
+[Filter Environment Variable Behaviors](LoaderInterfaceArchitecture.md#filter-environment-variable-behaviors)
+section of the [LoaderLayerInterface](LoaderLayerInterface.md) document.
+
+#### Driver Select Filtering
+
+The driver select environment variable `VK_LOADER_DRIVERS_SELECT` is a
+comma-delimited list of globs to search for in known drivers.
+
+If a driver is not selected when using the `VK_LOADER_DRIVERS_SELECT` filter,
+and loader logging is set to emit either warnings or driver messages, then a
+message will show for each driver that has been ignored.
 This message will look like the following:
 
 ```
@@ -163,16 +170,13 @@ WARNING | DRIVER: Driver "intel_icd.x86_64.json" ignored because not selected by
 ```
 
 If no drivers are found with a manifest filename that matches any of the
-provided globs, then no driver is enabled and it can result in Vulkan
-applications failing to run properly.
+provided globs, then no driver is enabled and may result in failures for
+any Vulkan application that is run.
+
+#### Driver Disable Filtering
 
 The driver disable environment variable `VK_LOADER_DRIVERS_DISABLE` is a
 comma-delimited list of globs to search for in known drivers.
-Since drivers don’t have a name like layers, this substring is used to compare
-against the manifest filename.
-Known driver manifests are those files that are already found by the loader
-taking into account default search paths and other environment variables
-(like `VK_ICD_FILENAMES` or `VK_ADD_DRIVER_FILES`).
 
 When a driver is disabled using the `VK_LOADER_DRIVERS_DISABLE` filter, and
 loader logging is set to emit either warnings or driver messages, then a message
@@ -186,44 +190,6 @@ WARNING | DRIVER: Driver "radeon_icd.x86_64.json" ignored because it was disable
 If no drivers are found with a manifest filename that matches any of the
 provided globs, then no driver is disabled.
 
-#### Comma-delimited lists
-
-All of the filter environment variables accept comma-delimited input.
-Therefore, you can chain multiple strings together and it will use the strings
-to individually enable or disable the appropriate item in the current list of
-available items.
-
-#### Globs
-
-To provide enough flexibility to limit driver name searches to only those
-desired by the developer, the loader uses a limited glob format for strings.
-Acceptable globs are:
- - Prefixes:   `"string*"`
- - Suffixes:   `"*string"`
- - Substrings:  `"*string*"`
- - Whole strings: `"string"`
-
-This is especially important because it is difficult sometimes to determine the
-full name of a driver manifest file.
-So, instead of having to type in `intel_icd.x86_64.json` to select only the
-Intel driver on Linux, the substring `*intel*` can be used in the
-`VK_LOADER_DRIVER_SELECT` environment variable.
-
-#### Case-insensitive
-
-All of the filter environment variables assume the strings inside of the glob
-are not case-sensitive.
-Therefore, “Bob”, “bob”, and “BOB” all amount to the same thing.
-
-#### Environment Variable Priority
-
-The values from the disable environment variable will be considered
-<b>before</b> the select environment variable.
-Because of this, it is possible to disable a driver using the disable
-environment variable, only to have it be re-enabled by the enable environment
-variable.
-
-
 ### Exception for Elevated Privileges
 
 For security reasons, `VK_ICD_FILENAMES`, `VK_DRIVER_FILES`, and
diff --git a/docs/LoaderInterfaceArchitecture.md b/docs/LoaderInterfaceArchitecture.md
index 1e4a98b9f..357be1b94 100644
--- a/docs/LoaderInterfaceArchitecture.md
+++ b/docs/LoaderInterfaceArchitecture.md
@@ -40,6 +40,12 @@
 - [Driver Interface With the Loader](#driver-interface-with-the-loader)
 - [Debugging Issues](#debugging-issues)
 - [Loader Policies](#loader-policies)
+- [Filter Environment Variable Behaviors](#filter-environment-variable-behaviors)
+  - [Comparison Strings](#comparison-strings)
+  - [Comma-Delimited Lists](#comma-delimited-lists)
+  - [Globs](#globs)
+  - [Case-Insensitive](#case-insensitive)
+  - [Environment Variable Priority](#environment-variable-priority)
 - [Table of Debug Environment Variables](#table-of-debug-environment-variables)
 - [Glossary of Terms](#glossary-of-terms)
 
@@ -490,6 +496,62 @@ sections listed below:
 <br/>
 <br/>
 
+## Filter Environment Variable Behaviors
+
+The filter environment variables provided in certain areas have some common
+restrictions and behaviors that should be listed.
+
+### Comparison Strings
+
+The filter variables will be compared against the appropriate strings for either
+drivers or layers.
+The appropriate string for layers is the layer name provided in the layer's
+manifest file.
+Since drivers don’t have a name like layers, this substring is used to compare
+against the driver manifest's filename.
+
+### Comma-Delimited Lists
+
+All of the filter environment variables accept comma-delimited input.
+Therefore, you can chain multiple strings together and it will use the strings
+to individually enable or disable the appropriate item in the current list of
+available items.
+
+### Globs
+
+To provide enough flexibility to limit name searches to only those wanted by the
+developer, the loader uses a limited glob format for strings.
+Acceptable globs are:
+ - Prefixes:   `"string*"`
+ - Suffixes:   `"*string"`
+ - Substrings:  `"*string*"`
+ - Whole strings: `"string"`
+   - In the case of whole strings, the string will be compared against each
+     layer or driver file name in its entirety.
+   - Because of this, it will only match the specific target such as:
+     `VK_LAYER_KHRONOS_validation` will match the layer name
+     `VK_LAYER_KHRONOS_validation`, but **not** a layer named
+     `VK_LAYER_KHRONOS_validation2` (not that there is such a layer).
+
+This is especially useful because it is difficult sometimes to determine the
+full name of a driver manifest file or even some commonly used layers
+such as `VK_LAYER_KHRONOS_validation`.
+
+### Case-Insensitive
+
+All of the filter environment variables assume the strings inside of the glob
+are not case-sensitive.
+Therefore, “Bob”, “bob”, and “BOB” all amount to the same thing.
+
+### Environment Variable Priority
+
+The values from the *disable* environment variable will be considered
+**before** the *enable* or *select* environment variable.
+Because of this, it is possible to disable a layer/driver using the *disable*
+environment variable, only to have it be re-enabled by the *enable*/*select*
+environment variable.
+This is useful if you disable all layers/drivers with the intent of only
+enabling a smaller subset of specific layers/drivers for issue triaging.
 
 ## Table of Debug Environment Variables
 
diff --git a/docs/LoaderLayerInterface.md b/docs/LoaderLayerInterface.md
index 91c9fc1a0..dab8846ad 100644
--- a/docs/LoaderLayerInterface.md
+++ b/docs/LoaderLayerInterface.md
@@ -26,12 +26,10 @@
   - [macOS Layer Discovery](#macos-layer-discovery)
     - [Example macOS Implicit Layer Search Path](#example-macos-implicit-layer-search-path)
   - [Layer Filtering](#layer-filtering)
+    - [Layer Enable Filtering](#layer-enable-filtering)
+    - [Layer Disable Filtering](#layer-disable-filtering)
     - [Layer Special Case Disable](#layer-special-case-disable)
     - [Layer Disable Warning](#layer-disable-warning)
-    - [Comma-delimited lists](#comma-delimited-lists)
-    - [Globs](#globs)
-    - [Case-insensitive](#case-insensitive)
-    - [Environment Variable Priority](#environment-variable-priority)
   - [Exception for Elevated Privileges](#exception-for-elevated-privileges)
 - [Layer Version Negotiation](#layer-version-negotiation)
 - [Layer Call Chains and Distributed Dispatch](#layer-call-chains-and-distributed-dispatch)
@@ -424,11 +422,23 @@ following:
 **NOTE:** This functionality is only available with Loaders built with version
 1.3.yyyy of the Vulkan headers and later.
 
+The loader supports filter environment variables which can forcibly enable and
+disable known layers.
+Known layers are those that are already found by the loader taking into account
+default search paths and other environment variables
+(like `VK_LAYER_PATH` or `VK_ADD_LAYER_PATH`).
+
+The filter variables will be compared against the layer name provided in the
+layer's manifest file.
+
+The filters must also follow the behaviors define in the
+[Filter Environment Variable Behaviors](LoaderInterfaceArchitecture.md#filter-environment-variable-behaviors)
+section of the [LoaderLayerInterface](LoaderLayerInterface.md) document.
+
+#### Layer Enable Filtering
+
 The layer enable environment variable `VK_LOADER_LAYERS_ENABLE` is a
 comma-delimited list of globs to search for in known layers.
-Known layers are those that are already found by the loader taking into account
-default search paths and other environment variables (like
-`VK_LAYER_PATH` or `VK_ADD_LAYER_PATH`).
 The layer names are compared against the globs listed in the environment
 variable, and if they match, they will automatically be added to the enabled
 layer list in the loader for each application.
@@ -443,11 +453,10 @@ This message will look like the following:
 WARNING | LAYER:  Layer "VK_LAYER_LUNARG_wrap_objects" force enabled due to env var 'VK_LOADER_LAYERS_ENABLE'
 ```
 
+#### Layer Disable Filtering
+
 The layer disable environment variable `VK_LOADER_LAYERS_DISABLE` is a
 comma-delimited list of globs to search for in known layers.
-Known layers are those that are already found by the loader taking into account
-default search paths and other environment variables
-(like `VK_LAYER_PATH` or `VK_ADD_LAYER_PATH`).
 The layer names are compared against the globs listed in the environment
 variable, and if they match, they will automatically be disabled (whether or not
 the layer is Implicit or Explicit).
@@ -492,44 +501,6 @@ Disabling layers, whether just through normal usage of
 `~all~` or `~explicit~` could cause application breakage if the application is
 relying on features provided by one or more explicit layers.
 
-#### Comma-delimited lists
-
-All of the filter environment variables accept comma-delimited input.
-Therefore, you can chain multiple strings together and it will use the strings
-to individually enable or disable the appropriate item in the current list of
-available items.
-
-#### Globs
-
-To provide enough flexibility to limit layer name searches to only those
-desired by the developer, the loader uses a limited glob format for strings.
-Acceptable globs are:
- - Prefixes:   `"string*"`
- - Suffixes:   `"*string"`
- - Substrings:  `"*string*"`
- - Whole strings: `"string"`
-
-This is especially important because it is difficult sometimes to determine the
-full name of a driver manifest file.
-So, instead of having to type in `VK_LAYER_KHRONOS_validation` into the older
-`VK_INSTANCE_LAYERS` environment variable to force on validation, the substring
-`*validation` can be used in the `VK_LOADER_LAYER_ENABLE` environment variable.
-
-#### Case-insensitive
-
-All of the filter environment variables assume the strings inside of the glob
-are not case-sensitive.
-Therefore, “Bob”, “bob”, and “BOB” all amount to the same thing.
-
-#### Environment Variable Priority
-
-The values from the disable environment variable will be considered
-<b>before</b> the enable environment variable.
-Because of this, it is possible to disable a layer using the disable environment
-variable, only to have it be re-enabled by the enable environment variable.
-This is useful if you disable all layers with the intent of only enabling a
-smaller subset of specific layers for issue triaging.
-
 ##### VK_INSTANCE_LAYERS
 
 The original `VK_INSTANCE_LAYERS` can be viewed as a special case of the new