Fixes #11017 - Clarify syntax of substitution expressions

reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md

@@ -1,7 +1,7 @@
 ---
 description: Describes regular expressions in PowerShell.
 Locale: en-US
-ms.date: 04/10/2023
+ms.date: 04/17/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_regular_expressions?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Regular Expressions
@@ -16,8 +16,7 @@ Describes regular expressions in PowerShell.
 > [!NOTE]
 > This article will show you the syntax and methods for using regular
 > expressions in PowerShell, not all syntax is discussed. For a more complete
-> reference, see the
-> [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference).
+> reference, see the [Regular Expression Language - Quick Reference][03].
 
 A regular expression is a pattern used to match text. It can be made up of
 literal characters, operators, and other constructs.
@@ -26,10 +25,10 @@ This article demonstrates regular expression syntax in PowerShell. PowerShell
 has several operators and cmdlets that use regular expressions. You can read
 more about their syntax and usage at the links below.
 
-- [Select-String](xref:Microsoft.PowerShell.Utility.Select-String)
-- [-match and -replace operators](about_Comparison_Operators.md#matching-operators)
-- [-split operator](about_Split.md)
-- [switch statement with -regex option](about_Switch.md)
+- [Select-String][10]
+- [-match and -replace operators][06]
+- [-split operator][08]
+- [switch statement with -regex option][09]
 
 PowerShell regular expressions are case-insensitive by default. Each method
 shown above has a different way to force case sensitivity.
@@ -70,8 +69,9 @@ range expression.
 
 ### Character ranges
 
-A pattern can also be a range of characters. The characters can be alphabetic `[A-Z]`,
-numeric `[0-9]`, or even ASCII-based `[ -~]` (all printable characters).
+A pattern can also be a range of characters. The characters can be alphabetic
+`[A-Z]`, numeric `[0-9]`, or even ASCII-based `[ -~]` (all printable
+characters).
 
 ```powershell
 # This expression returns true if the pattern matches any 2 digit number.
@@ -207,7 +207,7 @@ When using anchors in PowerShell, you should understand the difference between
   instead of matching every character EXCEPT the newline `\n`.
 
 To read more about these options and how to use them, visit the
-[Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference).
+[Regular Expression Language - Quick Reference][03].
 
 ## Escaping characters
 
@@ -374,27 +374,27 @@ N                              jsmith
 0                              A process has exited....
 ```
 
-For more information, see
-[Grouping Constructs in Regular Expressions](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions).
+For more information, see [Grouping Constructs in Regular Expressions][02].
 
 ### Substitutions in Regular Expressions
 
-Using the regular expressions with the `-replace` operator allows you to
-dynamically replace text using captured text.
+Using the regular expressions (regex) with the `-replace` operator allows you
+to dynamically replace text using captured text.
 
 `<input> -replace <original>, <substitute>`
 
 - `<input>`: The string to be searched
 - `<original>`: A regular expression used to search the input string
-- `<substitute>`: A regular expression substitution expression to replace
-  matches found in the input string.
+- `<substitute>`: A regex substitution expression to replace matches found in
+  the input string.
 
-> [!NOTE]
-> The `<original>` and `<substitute>` operands are subject to rules of the
-> regular expression engine such as character escaping.
+The `<original>` and `<substitute>` operands are subject to rules of the
+regular expression engine such as character escaping or substitution
+expressions. The replacement pattern can consist of one or more substitutions
+along with literal characters.
 
-Capturing groups can be referenced in the `<substitute>` string. The
-substitution is done by using the `$` character before the group identifier.
+Capture groups can be referenced in the `<substitute>` string using the `$`
+character before the group identifier.
 
 Two ways to reference capturing groups are by **Number** and by **Name**.
 
@@ -408,7 +408,7 @@ Two ways to reference capturing groups are by **Number** and by **Name**.
   [email protected]
   ```
 
-- By **Name** - Capturing Groups can also be referenced by name.
+- By **Name** - Capture Groups can also be referenced by name.
 
   ```powershell
   'CONTOSO\Administrator' -replace '\w+\\(?<user>\w+)', 'FABRIKAM\${user}'
@@ -457,9 +457,21 @@ Gobble Gobble
 > $5.72
 > ```
 
-For more information, see [Substitutions in Regular Expressions](/dotnet/standard/base-types/substitutions-in-regular-expressions).
+For detailed information on substitution expressions, see
+[Substitutions in Regular Expressions][04].
 
 ## See also
 
-- [about_Operators](about_Operators.md)
-- [about_Comparison_Operators](about_Comparison_Operators.md)
+- [about_Operators][07]
+- [about_Comparison_Operators][05]
+
+<!-- link references -->
+[02]: /dotnet/standard/base-types/grouping-constructs-in-regular-expressions
+[03]: /dotnet/standard/base-types/regular-expression-language-quick-reference
+[04]: /dotnet/standard/base-types/substitutions-in-regular-expressions
+[05]: about_Comparison_Operators.md
+[06]: about_Comparison_Operators.md#matching-operators
+[07]: about_Operators.md
+[08]: about_Split.md
+[09]: about_Switch.md
+[10]: xref:Microsoft.PowerShell.Utility.Select-String

reference/7.2/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md

@@ -1,7 +1,7 @@
 ---
 description: Describes regular expressions in PowerShell.
 Locale: en-US
-ms.date: 04/10/2023
+ms.date: 04/17/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_regular_expressions?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Regular Expressions
@@ -16,8 +16,7 @@ Describes regular expressions in PowerShell.
 > [!NOTE]
 > This article will show you the syntax and methods for using regular
 > expressions in PowerShell, not all syntax is discussed. For a more complete
-> reference, see the
-> [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference).
+> reference, see the [Regular Expression Language - Quick Reference][03].
 
 A regular expression is a pattern used to match text. It can be made up of
 literal characters, operators, and other constructs.
@@ -26,10 +25,10 @@ This article demonstrates regular expression syntax in PowerShell. PowerShell
 has several operators and cmdlets that use regular expressions. You can read
 more about their syntax and usage at the links below.
 
-- [Select-String](xref:Microsoft.PowerShell.Utility.Select-String)
-- [-match and -replace operators](about_Comparison_Operators.md#matching-operators)
-- [-split operator](about_Split.md)
-- [switch statement with -regex option](about_Switch.md)
+- [Select-String][10]
+- [-match and -replace operators][06]
+- [-split operator][08]
+- [switch statement with -regex option][09]
 
 PowerShell regular expressions are case-insensitive by default. Each method
 shown above has a different way to force case sensitivity.
@@ -70,8 +69,9 @@ range expression.
 
 ### Character ranges
 
-A pattern can also be a range of characters. The characters can be alphabetic `[A-Z]`,
-numeric `[0-9]`, or even ASCII-based `[ -~]` (all printable characters).
+A pattern can also be a range of characters. The characters can be alphabetic
+`[A-Z]`, numeric `[0-9]`, or even ASCII-based `[ -~]` (all printable
+characters).
 
 ```powershell
 # This expression returns true if the pattern matches any 2 digit number.
@@ -207,7 +207,7 @@ When using anchors in PowerShell, you should understand the difference between
   instead of matching every character EXCEPT the newline `\n`.
 
 To read more about these options and how to use them, visit the
-[Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference).
+[Regular Expression Language - Quick Reference][03].
 
 ## Escaping characters
 
@@ -374,27 +374,27 @@ N                              jsmith
 0                              A process has exited....
 ```
 
-For more information, see
-[Grouping Constructs in Regular Expressions](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions).
+For more information, see [Grouping Constructs in Regular Expressions][02].
 
 ### Substitutions in Regular Expressions
 
-Using the regular expressions with the `-replace` operator allows you to
-dynamically replace text using captured text.
+Using the regular expressions (regex) with the `-replace` operator allows you
+to dynamically replace text using captured text.
 
 `<input> -replace <original>, <substitute>`
 
 - `<input>`: The string to be searched
 - `<original>`: A regular expression used to search the input string
-- `<substitute>`: A regular expression substitution expression to replace
-  matches found in the input string.
+- `<substitute>`: A regex substitution expression to replace matches found in
+  the input string.
 
-> [!NOTE]
-> The `<original>` and `<substitute>` operands are subject to rules of the
-> regular expression engine such as character escaping.
+The `<original>` and `<substitute>` operands are subject to rules of the
+regular expression engine such as character escaping or substitution
+expressions. The replacement pattern can consist of one or more substitutions
+along with literal characters.
 
-Capturing groups can be referenced in the `<substitute>` string. The
-substitution is done by using the `$` character before the group identifier.
+Capture groups can be referenced in the `<substitute>` string using the `$`
+character before the group identifier.
 
 Two ways to reference capturing groups are by **Number** and by **Name**.
 
@@ -408,7 +408,7 @@ Two ways to reference capturing groups are by **Number** and by **Name**.
   [email protected]
   ```
 
-- By **Name** - Capturing Groups can also be referenced by name.
+- By **Name** - Capture Groups can also be referenced by name.
 
   ```powershell
   'CONTOSO\Administrator' -replace '\w+\\(?<user>\w+)', 'FABRIKAM\${user}'
@@ -457,9 +457,21 @@ Gobble Gobble
 > $5.72
 > ```
 
-For more information, see [Substitutions in Regular Expressions](/dotnet/standard/base-types/substitutions-in-regular-expressions).
+For detailed information on substitution expressions, see
+[Substitutions in Regular Expressions][04].
 
 ## See also
 
-- [about_Operators](about_Operators.md)
-- [about_Comparison_Operators](about_Comparison_Operators.md)
+- [about_Operators][07]
+- [about_Comparison_Operators][05]
+
+<!-- link references -->
+[02]: /dotnet/standard/base-types/grouping-constructs-in-regular-expressions
+[03]: /dotnet/standard/base-types/regular-expression-language-quick-reference
+[04]: /dotnet/standard/base-types/substitutions-in-regular-expressions
+[05]: about_Comparison_Operators.md
+[06]: about_Comparison_Operators.md#matching-operators
+[07]: about_Operators.md
+[08]: about_Split.md
+[09]: about_Switch.md
+[10]: xref:Microsoft.PowerShell.Utility.Select-String

reference/7.3/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md

@@ -1,7 +1,7 @@
 ---
 description: Describes regular expressions in PowerShell.
 Locale: en-US
-ms.date: 04/10/2023
+ms.date: 04/17/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_regular_expressions?view=powershell-7.3&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Regular Expressions
@@ -16,8 +16,7 @@ Describes regular expressions in PowerShell.
 > [!NOTE]
 > This article will show you the syntax and methods for using regular
 > expressions in PowerShell, not all syntax is discussed. For a more complete
-> reference, see the
-> [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference).
+> reference, see the [Regular Expression Language - Quick Reference][03].
 
 A regular expression is a pattern used to match text. It can be made up of
 literal characters, operators, and other constructs.
@@ -26,10 +25,10 @@ This article demonstrates regular expression syntax in PowerShell. PowerShell
 has several operators and cmdlets that use regular expressions. You can read
 more about their syntax and usage at the links below.
 
-- [Select-String](xref:Microsoft.PowerShell.Utility.Select-String)
-- [-match and -replace operators](about_Comparison_Operators.md#matching-operators)
-- [-split operator](about_Split.md)
-- [switch statement with -regex option](about_Switch.md)
+- [Select-String][10]
+- [-match and -replace operators][06]
+- [-split operator][08]
+- [switch statement with -regex option][09]
 
 PowerShell regular expressions are case-insensitive by default. Each method
 shown above has a different way to force case sensitivity.
@@ -70,8 +69,9 @@ range expression.
 
 ### Character ranges
 
-A pattern can also be a range of characters. The characters can be alphabetic `[A-Z]`,
-numeric `[0-9]`, or even ASCII-based `[ -~]` (all printable characters).
+A pattern can also be a range of characters. The characters can be alphabetic
+`[A-Z]`, numeric `[0-9]`, or even ASCII-based `[ -~]` (all printable
+characters).
 
 ```powershell
 # This expression returns true if the pattern matches any 2 digit number.
@@ -207,7 +207,7 @@ When using anchors in PowerShell, you should understand the difference between
   instead of matching every character EXCEPT the newline `\n`.
 
 To read more about these options and how to use them, visit the
-[Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference).
+[Regular Expression Language - Quick Reference][03].
 
 ## Escaping characters
 
@@ -374,27 +374,27 @@ N                              jsmith
 0                              A process has exited....
 ```
 
-For more information, see
-[Grouping Constructs in Regular Expressions](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions).
+For more information, see [Grouping Constructs in Regular Expressions][02].
 
 ### Substitutions in Regular Expressions
 
-Using the regular expressions with the `-replace` operator allows you to
-dynamically replace text using captured text.
+Using the regular expressions (regex) with the `-replace` operator allows you
+to dynamically replace text using captured text.
 
 `<input> -replace <original>, <substitute>`
 
 - `<input>`: The string to be searched
 - `<original>`: A regular expression used to search the input string
-- `<substitute>`: A regular expression substitution expression to replace
-  matches found in the input string.
+- `<substitute>`: A regex substitution expression to replace matches found in
+  the input string.
 
-> [!NOTE]
-> The `<original>` and `<substitute>` operands are subject to rules of the
-> regular expression engine such as character escaping.
+The `<original>` and `<substitute>` operands are subject to rules of the
+regular expression engine such as character escaping or substitution
+expressions. The replacement pattern can consist of one or more substitutions
+along with literal characters.
 
-Capturing groups can be referenced in the `<substitute>` string. The
-substitution is done by using the `$` character before the group identifier.
+Capture groups can be referenced in the `<substitute>` string using the `$`
+character before the group identifier.
 
 Two ways to reference capturing groups are by **Number** and by **Name**.
 
@@ -408,7 +408,7 @@ Two ways to reference capturing groups are by **Number** and by **Name**.
   [email protected]
   ```
 
-- By **Name** - Capturing Groups can also be referenced by name.
+- By **Name** - Capture Groups can also be referenced by name.
 
   ```powershell
   'CONTOSO\Administrator' -replace '\w+\\(?<user>\w+)', 'FABRIKAM\${user}'
@@ -457,9 +457,21 @@ Gobble Gobble
 > $5.72
 > ```
 
-For more information, see [Substitutions in Regular Expressions](/dotnet/standard/base-types/substitutions-in-regular-expressions).
+For detailed information on substitution expressions, see
+[Substitutions in Regular Expressions][04].
 
 ## See also
 
-- [about_Operators](about_Operators.md)
-- [about_Comparison_Operators](about_Comparison_Operators.md)
+- [about_Operators][07]
+- [about_Comparison_Operators][05]
+
+<!-- link references -->
+[02]: /dotnet/standard/base-types/grouping-constructs-in-regular-expressions
+[03]: /dotnet/standard/base-types/regular-expression-language-quick-reference
+[04]: /dotnet/standard/base-types/substitutions-in-regular-expressions
+[05]: about_Comparison_Operators.md
+[06]: about_Comparison_Operators.md#matching-operators
+[07]: about_Operators.md
+[08]: about_Split.md
+[09]: about_Switch.md
+[10]: xref:Microsoft.PowerShell.Utility.Select-String