Fixes #10888 - Clarify usefulness of --% (#10900)

* Fix broken links

* Clarify usefulness of --%

Author: sdwheeler

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

@@ -1,7 +1,7 @@
 ---
 description: Describes how PowerShell parses commands.
 Locale: en-US
-ms.date: 02/27/2023
+ms.date: 02/26/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Parsing
@@ -272,7 +272,8 @@ Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) token to
 stop PowerShell from interpreting input as PowerShell commands or expressions.
 
 > [!NOTE]
-> The stop-parsing token is only intended for use on Windows platforms.
+> The stop-parsing token is only intended for use native commands on Windows
+> platforms.
 
 When calling a native command, place the stop-parsing token before the program
 arguments. This technique is much easier than using escape characters to
@@ -317,8 +318,9 @@ PS> cmd /c --% echo "a|b"
 ```
 
 > [!NOTE]
-> Some commands on Windows systems are implemented as a Windows batch file. For
-> example, that `az` command for Azure CLI is a Windows batch file.
+> The stop-parsing token isn't needed when using PowerShell cmdlets. However,
+> it could be useful to pass arguments to a PowerShell function that is
+> designed to call a native command with those arguments.
 
 ### Passing arguments that contain quote characters
 

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

@@ -1,7 +1,7 @@
 ---
 description: Describes the special character sequences that control how PowerShell interprets the next characters in the sequence.
 Locale: en-US
-ms.date: 01/11/2023
+ms.date: 02/23/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Special Characters
@@ -225,24 +225,20 @@ PowerShell sends the following string to `Icacls`.
 X:\VMS /grant Dom\HVAdmin:(CI)(OI)F
 ```
 
-Here is another example. The **showArgs** function outputs the values passed to
-it. In this example, we pass the variable named `$HOME` to the function twice.
+In this second example, we pass the variable `$HOME` to the `cmd.exe /c echo`
+command twice.
 
 ```powershell
-function showArgs {
-  "`$args = " + ($args -join '|')
-}
-
-showArgs $HOME --% $HOME
+cmd.exe /c echo $HOME --% $HOME
 ```
 
-You can see in the output that, for the first parameter, the variable `$HOME`
-is interpreted by PowerShell so that the value of the variable is passed to the
-function. The second use of `$HOME` comes after the stop-parsing token, so the
-string "$HOME" is passed to the function without interpretation.
+The output shows that the first instance of `$HOME` is interpreted by
+PowerShell so that the value of the variable is passed to `cmd`. The second
+instance of `$HOME` comes after the stop-parsing token, so it is passed as a
+literal string.
 
 ```Output
-$args = C:\Users\username|--%|$HOME
+C:\Users\username  $HOME
 ```
 
 For more information about the stop-parsing token, see [about_Parsing][02].

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

@@ -1,7 +1,7 @@
 ---
 description: Describes how PowerShell parses commands.
 Locale: en-US
-ms.date: 02/27/2023
+ms.date: 02/26/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Parsing
@@ -272,7 +272,8 @@ Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) token to
 stop PowerShell from interpreting input as PowerShell commands or expressions.
 
 > [!NOTE]
-> The stop-parsing token is only intended for use on Windows platforms.
+> The stop-parsing token is only intended for use native commands on Windows
+> platforms.
 
 When calling a native command, place the stop-parsing token before the program
 arguments. This technique is much easier than using escape characters to
@@ -317,8 +318,9 @@ PS> cmd /c --% echo "a|b"
 ```
 
 > [!NOTE]
-> Some commands on Windows systems are implemented as a Windows batch file. For
-> example, that `az` command for Azure CLI is a Windows batch file.
+> The stop-parsing token isn't needed when using PowerShell cmdlets. However,
+> it could be useful to pass arguments to a PowerShell function that is
+> designed to call a native command with those arguments.
 
 ### Passing arguments that contain quote characters
 

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

@@ -1,7 +1,7 @@
 ---
 description: Describes the special character sequences that control how PowerShell interprets the next characters in the sequence.
 Locale: en-US
-ms.date: 01/11/2023
+ms.date: 02/23/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Special Characters
@@ -273,24 +273,20 @@ PowerShell sends the following string to `Icacls`.
 X:\VMS /grant Dom\HVAdmin:(CI)(OI)F
 ```
 
-Here is another example. The **showArgs** function outputs the values passed to
-it. In this example, we pass the variable named `$HOME` to the function twice.
+In this second example, we pass the variable `$HOME` to the `cmd.exe /c echo`
+command twice.
 
 ```powershell
-function showArgs {
-  "`$args = " + ($args -join '|')
-}
-
-showArgs $HOME --% $HOME
+cmd.exe /c echo $HOME --% $HOME
 ```
 
-You can see in the output that, for the first parameter, the variable `$HOME`
-is interpreted by PowerShell so that the value of the variable is passed to the
-function. The second use of `$HOME` comes after the stop-parsing token, so the
-string "$HOME" is passed to the function without interpretation.
+The output shows that the first instance of `$HOME` is interpreted by
+PowerShell so that the value of the variable is passed to `cmd`. The second
+instance of `$HOME` comes after the stop-parsing token, so it is passed as a
+literal string.
 
 ```Output
-$args = C:\Users\username|--%|$HOME
+C:\Users\username  $HOME
 ```
 
 For more information about the stop-parsing token, see [about_Parsing][02].

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

@@ -1,7 +1,7 @@
 ---
 description: Describes how PowerShell parses commands.
 Locale: en-US
-ms.date: 02/27/2023
+ms.date: 02/26/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.3&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Parsing
@@ -272,7 +272,8 @@ Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) token to
 stop PowerShell from interpreting input as PowerShell commands or expressions.
 
 > [!NOTE]
-> The stop-parsing token is only intended for use on Windows platforms.
+> The stop-parsing token is only intended for use native commands on Windows
+> platforms.
 
 When calling a native command, place the stop-parsing token before the program
 arguments. This technique is much easier than using escape characters to
@@ -317,8 +318,9 @@ PS> cmd /c --% echo "a|b"
 ```
 
 > [!NOTE]
-> Some commands on Windows systems are implemented as a Windows batch file. For
-> example, that `az` command for Azure CLI is a Windows batch file.
+> The stop-parsing token isn't needed when using PowerShell cmdlets. However,
+> it could be useful to pass arguments to a PowerShell function that is
+> designed to call a native command with those arguments.
 
 ### Passing arguments that contain quote characters
 

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

@@ -1,7 +1,7 @@
 ---
 description: Describes the special character sequences that control how PowerShell interprets the next characters in the sequence.
 Locale: en-US
-ms.date: 01/11/2023
+ms.date: 02/23/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-7.3&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Special Characters
@@ -195,7 +195,7 @@ This example outputs the **up down arrow** (↕) symbol.
 ## Vertical tab (`v)
 
 The vertical tab (`` `v ``) character advances to the next vertical tab stop
-and writes the remaining output at that point. The rendering of the
+and writes the remaining output at that point. The rendering of the the
 vertical tab is device and terminal dependent.
 
 ```powershell
@@ -273,24 +273,20 @@ PowerShell sends the following string to `Icacls`.
 X:\VMS /grant Dom\HVAdmin:(CI)(OI)F
 ```
 
-Here is another example. The **showArgs** function outputs the values passed to
-it. In this example, we pass the variable named `$HOME` to the function twice.
+In this second example, we pass the variable `$HOME` to the `cmd.exe /c echo`
+command twice.
 
 ```powershell
-function showArgs {
-  "`$args = " + ($args -join '|')
-}
-
-showArgs $HOME --% $HOME
+cmd.exe /c echo $HOME --% $HOME
 ```
 
-You can see in the output that, for the first parameter, the variable `$HOME`
-is interpreted by PowerShell so that the value of the variable is passed to the
-function. The second use of `$HOME` comes after the stop-parsing token, so the
-string "$HOME" is passed to the function without interpretation.
+The output shows that the first instance of `$HOME` is interpreted by
+PowerShell so that the value of the variable is passed to `cmd`. The second
+instance of `$HOME` comes after the stop-parsing token, so it is passed as a
+literal string.
 
 ```Output
-$args = C:\Users\username|--%|$HOME
+C:\Users\username  $HOME
 ```
 
 For more information about the stop-parsing token, see [about_Parsing][02].

reference/7.4/Microsoft.PowerShell.Core/About/about_Parsing.md

@@ -1,7 +1,7 @@
 ---
 description: Describes how PowerShell parses commands.
 Locale: en-US
-ms.date: 02/27/2023
+ms.date: 02/26/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.4&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Parsing
@@ -272,7 +272,8 @@ Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) token to
 stop PowerShell from interpreting input as PowerShell commands or expressions.
 
 > [!NOTE]
-> The stop-parsing token is only intended for use on Windows platforms.
+> The stop-parsing token is only intended for use native commands on Windows
+> platforms.
 
 When calling a native command, place the stop-parsing token before the program
 arguments. This technique is much easier than using escape characters to
@@ -317,8 +318,9 @@ PS> cmd /c --% echo "a|b"
 ```
 
 > [!NOTE]
-> Some commands on Windows systems are implemented as a Windows batch file. For
-> example, that `az` command for Azure CLI is a Windows batch file.
+> The stop-parsing token isn't needed when using PowerShell cmdlets. However,
+> it could be useful to pass arguments to a PowerShell function that is
+> designed to call a native command with those arguments.
 
 ### Passing arguments that contain quote characters
 

reference/7.4/Microsoft.PowerShell.Core/About/about_Special_Characters.md

@@ -1,7 +1,7 @@
 ---
 description: Describes the special character sequences that control how PowerShell interprets the next characters in the sequence.
 Locale: en-US
-ms.date: 01/11/2023
+ms.date: 02/23/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-7.4&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Special Characters
@@ -273,24 +273,20 @@ PowerShell sends the following string to `Icacls`.
 X:\VMS /grant Dom\HVAdmin:(CI)(OI)F
 ```
 
-Here is another example. The **showArgs** function outputs the values passed to
-it. In this example, we pass the variable named `$HOME` to the function twice.
+In this second example, we pass the variable `$HOME` to the `cmd.exe /c echo`
+command twice.
 
 ```powershell
-function showArgs {
-  "`$args = " + ($args -join '|')
-}
-
-showArgs $HOME --% $HOME
+cmd.exe /c echo $HOME --% $HOME
 ```
 
-You can see in the output that, for the first parameter, the variable `$HOME`
-is interpreted by PowerShell so that the value of the variable is passed to the
-function. The second use of `$HOME` comes after the stop-parsing token, so the
-string "$HOME" is passed to the function without interpretation.
+The output shows that the first instance of `$HOME` is interpreted by
+PowerShell so that the value of the variable is passed to `cmd`. The second
+instance of `$HOME` comes after the stop-parsing token, so it is passed as a
+literal string.
 
 ```Output
-$args = C:\Users\username|--%|$HOME
+C:\Users\username  $HOME
 ```
 
 For more information about the stop-parsing token, see [about_Parsing][02].

reference/7.5/Microsoft.PowerShell.Core/About/about_Parsing.md

@@ -1,7 +1,7 @@
 ---
 description: Describes how PowerShell parses commands.
 Locale: en-US
-ms.date: 02/27/2023
+ms.date: 02/26/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.5&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Parsing
@@ -272,7 +272,8 @@ Beginning in PowerShell 3.0, you can use the _stop-parsing_ (`--%`) token to
 stop PowerShell from interpreting input as PowerShell commands or expressions.
 
 > [!NOTE]
-> The stop-parsing token is only intended for use on Windows platforms.
+> The stop-parsing token is only intended for use native commands on Windows
+> platforms.
 
 When calling a native command, place the stop-parsing token before the program
 arguments. This technique is much easier than using escape characters to
@@ -317,8 +318,9 @@ PS> cmd /c --% echo "a|b"
 ```
 
 > [!NOTE]
-> Some commands on Windows systems are implemented as a Windows batch file. For
-> example, that `az` command for Azure CLI is a Windows batch file.
+> The stop-parsing token isn't needed when using PowerShell cmdlets. However,
+> it could be useful to pass arguments to a PowerShell function that is
+> designed to call a native command with those arguments.
 
 ### Passing arguments that contain quote characters
 

reference/7.5/Microsoft.PowerShell.Core/About/about_Special_Characters.md

@@ -1,7 +1,7 @@
 ---
 description: Describes the special character sequences that control how PowerShell interprets the next characters in the sequence.
 Locale: en-US
-ms.date: 01/11/2023
+ms.date: 02/23/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-7.5&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Special Characters
@@ -273,24 +273,20 @@ PowerShell sends the following string to `Icacls`.
 X:\VMS /grant Dom\HVAdmin:(CI)(OI)F
 ```
 
-Here is another example. The **showArgs** function outputs the values passed to
-it. In this example, we pass the variable named `$HOME` to the function twice.
+In this second example, we pass the variable `$HOME` to the `cmd.exe /c echo`
+command twice.
 
 ```powershell
-function showArgs {
-  "`$args = " + ($args -join '|')
-}
-
-showArgs $HOME --% $HOME
+cmd.exe /c echo $HOME --% $HOME
 ```
 
-You can see in the output that, for the first parameter, the variable `$HOME`
-is interpreted by PowerShell so that the value of the variable is passed to the
-function. The second use of `$HOME` comes after the stop-parsing token, so the
-string "$HOME" is passed to the function without interpretation.
+The output shows that the first instance of `$HOME` is interpreted by
+PowerShell so that the value of the variable is passed to `cmd`. The second
+instance of `$HOME` comes after the stop-parsing token, so it is passed as a
+literal string.
 
 ```Output
-$args = C:\Users\username|--%|$HOME
+C:\Users\username  $HOME
 ```
 
 For more information about the stop-parsing token, see [about_Parsing][02].