Update documentation in regards to CASE and FORCECASE

facelessuser · facelessuser · commit a6e78d382fb5 · 2019-08-06T21:40:52.000-06:00
diff --git a/docs/src/markdown/fnmatch.md b/docs/src/markdown/fnmatch.md
@@ -138,11 +138,25 @@ def translate(patterns, *, flags=0):
 
 `FORCECASE` forces case sensitivity. `FORCECASE` has higher priority than [`IGNORECASE`](#fnmatchignorecase).
 
-On Windows, this will force names to be treated like Linux/Unix names, and slashes will not be normalized. It is recommended to use [`FORCEUNIX`](#fnmatchforceunix) if the desire is to force Linux/Unix style logic. It is more intuitive when reading the code and can allow combinations with `IGNORECASE` if a case insensitive Linux/Unix style is preferred. Currently, Windows is the only system that is treated case insensitively by default.
+On Windows, this will force names to be treated like Linux/Unix names, and slashes will not be normalized.
+
+!!! warning "Deprecated 4.3.0"
+    `FORCECASE` has been deprecated as of 4.3.0.
+
+    It is recommended to use [`FORCEUNIX`](#fnmatchforceunix) if the desire is to force Linux/Unix style logic. It is more intuitive when reading the code and can allow combinations with `IGNORECASE` if a case insensitive Linux/Unix style is preferred. Currently, Windows is the only system that is treated case insensitively by default.
+
+    If you'd like to force case sensitivity, even on Windows, it is recommended to use [`CASE`](#fnmatchcase). `CASE` can also be paired with the [`FORCEWIN`](#fnmatchforceunix) flag if desired.
+
+#### `fnmatch.CASE, fnmatch.C` {: #fnmatchcase}
+
+`CASE` forces case sensitivity. `CASE` has higher priority than [`IGNORECASE`](#fnmatchignorecase).
+
+!!! new "New 4.3.0"
+    `CASE` is new in 4.3.0.
 
 #### `fnmatch.IGNORECASE, fnmatch.I` {: #fnmatchignorecase}
 
-`IGNORECASE` forces case insensitivity. [`FORCECASE`](#fnmatchforcecase) has higher priority than `IGNORECASE`.
+`IGNORECASE` forces case insensitivity. [`CASE`](#fnmatchcase) has higher priority than `IGNORECASE`.
 
 #### `fnmatch.RAWCHARS, fnmatch.R` {: #fnmatchrawchars}
 
@@ -154,13 +168,13 @@ On Windows, this will force names to be treated like Linux/Unix names, and slash
 
 If it is desired, you can force exclusion patterns, when no inclusion pattern is provided, to assume all files match unless the file matches the excluded pattern. This is done with the [`NEGATEALL`](#fnmatchnegateall) flag.
 
-If used with the extended glob feature, patterns like `!(inverse|pattern)` will be mistakenly parsed as an exclusion pattern instead of as an inverse extended glob group.  See [`MINUSNEGATE`](#fnmatchminusgate) for an alternative syntax that plays nice with extended glob.
+If used with the extended match feature, patterns like `!(inverse|pattern)` will be mistakenly parsed as an exclusion pattern instead of as an inverse extended glob group.  See [`MINUSNEGATE`](#fnmatchminusgate) for an alternative syntax that plays nice with extended glob.
 
 !!! warning "Changes 4.0"
     In 4.0, `NEGATE` now requires a non-exclusion pattern to be paired with it or it will match nothing. If you really
     need something similar to the old behavior, that would assume a default inclusion pattern, you can use the [`NEGATEALL`](#fnmatchnegateall).
 
-#### `fnmatch.NEGATEALL, glob.A` {: #fnmatchnegateall}
+#### `fnmatch.NEGATEALL, fnmatch.A` {: #fnmatchnegateall}
 
 `NEGATEALL` can force exclusion patterns, when no inclusion pattern is provided, to assume all files match unless the file matches the excluded pattern. Essentially, it means if you use a pattern such as `!*.md`, it will assume two patterns were given: `*` and `!*.md`, where `!*.md` is applied to the results of `*`.
 
@@ -172,7 +186,7 @@ When `MINUSNEGATE` is used with [`NEGATE`](#fnmatchnegate), exclusion patterns a
 
 #### `fnmatch.DOTMATCH, fnmatch.D` {: #fnmatchdotmatch}
 
-By default, [`glob`](#fnmatchfnmatch) and related functions will not match file or directory names that start with dot `.` unless matched with a literal dot. `DOTMATCH` allows the meta characters (such as `*`) to match dots like any other character. Dots will not be matched in `[]`, `*`, or `?`.
+By default, [`fnmatch`](#fnmatchfnmatch) and related functions will not match file or directory names that start with dot `.` unless matched with a literal dot. `DOTMATCH` allows the meta characters (such as `*`) to match dots like any other character. Dots will not be matched in `[]`, `*`, or `?`.
 
 #### `fnmatch.EXTMATCH, fnmatch.E` {: #fnmatchextmatch}
 
@@ -202,8 +216,6 @@ True
 
 `FORCEWIN` will force Windows name and case logic to be used on Linux/Unix systems. It will also cause slashes to be normalized. This is great if you need to match Windows specific names on a Linux/Unix system.
 
-When using `FORCEWIN`, [`FORCECASE`](#fnmatchforcecase) will be ignored as paths on Windows are not case sensitive.
-
 If `FORCEWIN` is used along side [`FORCEUNIX`](#fnmatchforceunix), both will be ignored.
 
 !!! new "New 4.2.0"
diff --git a/docs/src/markdown/glob.md b/docs/src/markdown/glob.md
@@ -38,9 +38,9 @@ Pattern           | Meaning
 
 - Meta characters have no effect when inside a UNC path: `\\\\Server?\\mount*\\`.
 
-- If [`FORCECASE`](#globforcecase) or [`FORCEUNIX`](#globforceunix) are applied on a Windows system, match and filter commands that do not touch the file system will not have slashes normalized. In addition, drive letters will also not be handled. Essentially, paths will be treated as if on Linux/Unix. Commands on Windows that do touch the file system will ignore `FORCECASE` and `FORCEUNIX`. [`glob`](#globglob) and [`iglob`](#globiglob) will ignore `FORCECASE` on Windows. [`globmatch`](#globglobmatch) and [`globfilter`](#globglobfilter), will also ignore `FORCECASE` if the [`REALPATH`](#globrealpath) flag is enabled.
+- If [`FORCEUNIX`](#globforceunix) is applied on a Windows system, match and filter commands that do not touch the file system will not have slashes normalized. In addition, drive letters will also not be handled. Essentially, paths will be treated as if on Linux/Unix. Commands that do touch the file system ([`glob`](#globglob) and [`iglob`](#globiglob)) will ignore `FORCEUNIX` and [`FORCEWIN`](#globforcewin). [`globmatch`](#globglobmatch) and [`globfilter`](#globglobfilter), will also ignore `FORCEUNIX` and `FORCEWIN` if the [`REALPATH`](#globrealpath) flag is enabled.
 
-    The reverse applies when [`FORCEWIN`](#globforcewin) is used on a Linux/Unix system.
+    [`FORCEWIN`](#globforcewin) will do the opposite on a Linux/Unix system, and will force non-Windows logic on a Windows system. Like with `FORCEUNIX`, it only applies to commands that don't touch the file system.
 
 - By default, file and directory names starting with `.` are only matched with literal `.`.  The patterns `*`, `**`, `?`, and `[]` will not match a leading `.`.  To alter this behavior, you can use the [`DOTGLOB`](#globdotglob) flag, but even with `DOTGLOB` these special tokens will not match a special directory (`.` or `..`).  But when a literal `.` is used at the start of the filename, for instance in the pattern `.*`, `.` and `..` can potentially be matched.
 
@@ -289,11 +289,26 @@ True
 
 On Windows, `FORCECASE` will also force paths to be treated like Linux/Unix paths in [`globmatch`](#globglobmatch) and [`globfilter`](#globfilter), but only when [`REALPATH`](#globrealpath) is not enabled. `iglob`, `glob`, and cases when `REALPATH` is enabled must normalize paths and use Windows logic as these operations are performed on the current file system of the host machine. File system operations should not enable `FORCECASE` on Windows as it provides no meaningful results. But, if you wish to evaluate Linux/Unix paths on a Windows machine, without touching the file system, then `FORCECASE` might be useful.
 
-It is recommended to use [`FORCEUNIX`](#globforceunix) if the desire is to force Linux/Unix style logic. It is more intuitive when reading the code and can allow combinations with `IGNORECASE` if a case insensitive Linux/Unix style is preferred. Currently, Windows is the only system that is treated case insensitively by default.
+!!! warning "Deprecated 4.3.0"
+
+    `FORCECASE` is deprecated in 4.3.0.
+
+    It is recommended to use [`FORCEUNIX`](#globforceunix) if the desire is to force Linux/Unix style logic. It is more intuitive when reading the code and can allow combinations with `IGNORECASE` if a case insensitive Linux/Unix style is preferred.
+
+    If you'd like to force case sensitivity, even on Windows, it is recommended to use [`CASE`](#globcase). `CASE` can also be paired with the [`FORCEWIN`](#globforceunix) flag if desired.
+
+#### `glob.CASE, glob.C` {: #globcase}
+
+`CASE` forces case sensitivity. `CASE` has higher priority than [`IGNORECASE`](#globignorecase).
+
+On Windows, drive letters (`C:`) and UNC host/share (`//host/share`) portions of a path will still be treated case insensitively, but the rest of the path will have case sensitive logic applied.
+
+!!! new "New 4.3.0"
+    `CASE` is new in 4.3.0.
 
 #### `glob.IGNORECASE, glob.I` {: #globignorecase}
 
-`IGNORECASE` forces case insensitivity. [`FORCECASE`](#globforcecase) has higher priority than `IGNORECASE`.
+`IGNORECASE` forces case insensitivity. [`CASE`](#globcase) has higher priority than `IGNORECASE`.
 
 #### `glob.RAWCHARS, glob.R` {: #globrawchars}
 
@@ -339,7 +354,7 @@ When `MINUSNEGATE` is used with [`NEGATE`](#globnegate), exclusion patterns are
 
 In the past, only `glob` and `iglob` operated on the filesystem, but with `REALPATH`, other functions will now operate on the filesystem as well: `globmatch` and `globfilter`.
 
-Traditionally, functions such as `globmatch` would simply match a path with regular expression and return the result. It was not concerned with whether the path existed or not. It didn't care if it was even valid for the operating system as `FORCECASE` would force Linux/Unix path logic on Windows.
+Normally, functions such as `globmatch` would simply match a path with regular expression and return the result. The functions were not concerned with whether the path existed or not. It didn't care if it was even valid for the operating system.
 
 `REALPATH` forces `globmatch` and `globfilter` to treat the string path as a real file path for the given system it is running on. It will augment the patterns used to match files and enable additional logic that the path must meet in order to match:
 
@@ -348,6 +363,8 @@ Traditionally, functions such as `globmatch` would simply match a path with regu
 - When presented with a pattern where the match must be a directory, but the file path being compared doesn't indicate the file is a directory with a trailing slash, the command will look at the filesystem to determine if it is a directory.
 - Paths must match in relation to the current working directory unless the pattern is constructed in a way to indicates an absolute path.
 
+Since `REALPATH` causes the file system to be referenced when matching a path, flags such as [`FORCEUNIX`](#globforceunix) and [`FORCEWIN`](#globforcewin) are not allowed with this flag and will be ignored.
+
 !!! new "NEW 3.0"
     `REALPATH` was added in 3.0.
 
@@ -437,8 +454,6 @@ from wcmatch import glob
 
 `FORCEWIN` will force Windows path and case logic to be used on Linux/Unix systems. It will also cause slashes to be normalized and Windows drive syntax to be handled special. This is great if you need to match Windows specific paths on a Linux/Unix system. This will only work on commands that do not access the file system: `translate`, `globmatch`, `globfilter`, etc. These flags will not work with `glob` or `iglob`. It also will not work when using the [`REALPATH`](#globrealpath) flag with things like `globmatch` and `globfilter`.
 
-When using `FORCEWIN`, [`FORCECASE`](#globforcecase) will be ignored as paths on Windows are not case sensitive.
-
 If `FORCEWIN` is used along side [`FORCEUNIX`](#globforceunix), both will be ignored.
 
 !!! new "New 4.2.0"
diff --git a/docs/src/markdown/wcmatch.md b/docs/src/markdown/wcmatch.md
@@ -279,9 +279,22 @@ is called on every new `match` call.
 
 `FORCECASE` does not apply to Windows systems.
 
+!!! warning "Deprecated 4.3.0"
+
+    `FORCECASE` is deprecated in 4.3.0.
+
+    If you'd like to force case sensitivity, even on Windows, it is recommended to use [`CASE`](#wcmatchcase).
+
+#### `wcmatch.CASE, wcmatch.C` {: #wcmatchcase}
+
+`CASE` forces case sensitivity. `CASE` has higher priority than [`IGNORECASE`](#wcmatchignorecase).
+
+!!! new "New 4.3.0"
+    `CASE` is new in 4.3.0.
+
 #### `wcmatch.IGNORECASE, wcmatch.I` {: #wcmatchignorecase}
 
-`IGNORECASE` forces case insensitive searches. `FORCECASE` has higher priority than [`IGNORECASE`](#wcmatchignorecase).
+`IGNORECASE` forces case insensitive searches. [`CASE`](#wcmatchcase) has higher priority than `IGNORECASE`.
 
 #### `wcmatch.RAWCHARS, wcmatch.R` {: #wcmatchrawchars}
 
