(GH-11401) Clarify smart quotes behavior/guidance (#11404)

michaeltlombardi · web-flow · commit 46df435f0bb8 · 2024-09-09T15:09:29.000-05:00
Prior to this change, the `about_Quoting_Rules` topic document didn't indicate that PowerShell treats smart/typographic quotation marks as normal/programmer quotation marks, making them subject to the same escaping and quoting behaviors. This change: - Adds a note about smart quotation marks and guidance to avoid using them to enclose strings. - Adds an example of escaping smart quotation marks. - Fixes AB#309820 - Resolves #11401
diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md
@@ -1,7 +1,7 @@
 ---
 description: Describes rules for using single and double quotation marks in PowerShell.
 Locale: en-US
-ms.date: 09/04/2024
+ms.date: 09/09/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Quoting_Rules
@@ -34,6 +34,16 @@ command that are run on the remote computer. In a remote session, quotation
 marks also determine whether the variables in a command are interpreted first
 on the local computer or on the remote computer.
 
+> PowerShell treats smart quotation marks, also called typographic or curly
+> quotes, as normal quotation marks for strings. Don't use smart quotation
+> marks to enclose strings. When writing strings that contain smart quotation
+> marks, follow the guidance in the
+> [Including quote characters in a string](#including-quote-characters-in-a-string)
+> section of this document.
+>
+> For more information about smart quotation marks, see the _Smart Quotes_
+> section in the Wikipedia article [Quotation marks in English][02].
+
 ## Double-quoted strings
 
 A string enclosed in double quotation marks is an _expandable_ string. Variable
@@ -75,7 +85,7 @@ enclosed in a subexpression. For example:
 ```
 
 ```Output
-PS version: 5.1.19041.1151
+PS version: 7.2.0
 ```
 
 To separate a variable name from subsequent characters in the string, enclose
@@ -204,6 +214,20 @@ Use a quotation mark (") to begin a string.
 Use a quotation mark (`") to begin a string.
 ```
 
+Because PowerShell interprets smart quotation marks, like `‘`, `'`, `“`, and
+`”`, as normal quotation marks, smart quotation marks also need to be escaped.
+For example:
+
+```powershell
+"Double ““smart quotation marks`” must be escaped in a double-quoted string."
+'Single ‘‘smart quotation marks’’ must be escaped in a single-quoted string.'
+```
+
+```Output
+Double “smart quotation marks” must be escaped in a double-quoted string.
+Single ‘smart quotation marks’ must be escaped in a single-quoted string.
+```
+
 ## Here-strings
 
 The quotation rules for here-strings are slightly different.
@@ -360,7 +384,7 @@ see in the console.
 Collections, including arrays, are converted to strings by placing a single
 space between the string representations of the elements. A different separator
 can be specified by setting preference variable `$OFS`. For more information,
-see the [`$OFS` preference variable][03].
+see the [`$OFS` preference variable][04].
 
 Instances of any other type are converted to strings by calling the
 `ToString()` method, which may not give a meaningful representation. For
@@ -430,16 +454,17 @@ Some native commands expect arguments that contain quote characters. PowerShell
 interprets the quoted string before passing it to the external command. This
 interpretation removes the outer quote characters.
 
-For more information about this behavior, see the [about_Parsing][02] article.
+For more information about this behavior, see the [about_Parsing][03] article.
 
 ## See also
 
-- [about_Special_Characters][04]
-- [ConvertFrom-StringData][05]
+- [about_Special_Characters][05]
+- [ConvertFrom-StringData][06]
 
 <!-- link references -->
 [01]: about_Parsing.md#argument-mode
-[02]: about_Parsing.md#passing-arguments-that-contain-quote-characters
-[03]: about_preference_variables.md#ofs
-[04]: about_Special_Characters.md
-[05]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData
+[02]: https://en.wikipedia.org/wiki/Quotation_marks_in_English#Smart_quotes
+[03]: about_Parsing.md#passing-arguments-that-contain-quote-characters
+[04]: about_preference_variables.md#ofs
+[05]: about_Special_Characters.md
+[06]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData
diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md
@@ -1,7 +1,7 @@
 ---
 description: Describes rules for using single and double quotation marks in PowerShell.
 Locale: en-US
-ms.date: 09/04/2024
+ms.date: 09/09/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Quoting_Rules
@@ -34,6 +34,16 @@ command that are run on the remote computer. In a remote session, quotation
 marks also determine whether the variables in a command are interpreted first
 on the local computer or on the remote computer.
 
+> PowerShell treats smart quotation marks, also called typographic or curly
+> quotes, as normal quotation marks for strings. Don't use smart quotation
+> marks to enclose strings. When writing strings that contain smart quotation
+> marks, follow the guidance in the
+> [Including quote characters in a string](#including-quote-characters-in-a-string)
+> section of this document.
+>
+> For more information about smart quotation marks, see the _Smart Quotes_
+> section in the Wikipedia article [Quotation marks in English][02].
+
 ## Double-quoted strings
 
 A string enclosed in double quotation marks is an _expandable_ string. Variable
@@ -204,6 +214,20 @@ Use a quotation mark (") to begin a string.
 Use a quotation mark (`") to begin a string.
 ```
 
+Because PowerShell interprets smart quotation marks, like `‘`, `'`, `“`, and
+`”`, as normal quotation marks, smart quotation marks also need to be escaped.
+For example:
+
+```powershell
+"Double ““smart quotation marks`” must be escaped in a double-quoted string."
+'Single ‘‘smart quotation marks’’ must be escaped in a single-quoted string.'
+```
+
+```Output
+Double “smart quotation marks” must be escaped in a double-quoted string.
+Single ‘smart quotation marks’ must be escaped in a single-quoted string.
+```
+
 ## Here-strings
 
 The quotation rules for here-strings are slightly different.
@@ -360,7 +384,7 @@ see in the console.
 Collections, including arrays, are converted to strings by placing a single
 space between the string representations of the elements. A different separator
 can be specified by setting preference variable `$OFS`. For more information,
-see the [`$OFS` preference variable][03].
+see the [`$OFS` preference variable][04].
 
 Instances of any other type are converted to strings by calling the
 `ToString()` method, which may not give a meaningful representation. For
@@ -430,16 +454,17 @@ Some native commands expect arguments that contain quote characters. PowerShell
 interprets the quoted string before passing it to the external command. This
 interpretation removes the outer quote characters.
 
-For more information about this behavior, see the [about_Parsing][02] article.
+For more information about this behavior, see the [about_Parsing][03] article.
 
 ## See also
 
-- [about_Special_Characters][04]
-- [ConvertFrom-StringData][05]
+- [about_Special_Characters][05]
+- [ConvertFrom-StringData][06]
 
 <!-- link references -->
 [01]: about_Parsing.md#argument-mode
-[02]: about_Parsing.md#passing-arguments-that-contain-quote-characters
-[03]: about_preference_variables.md#ofs
-[04]: about_Special_Characters.md
-[05]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData
+[02]: https://en.wikipedia.org/wiki/Quotation_marks_in_English#Smart_quotes
+[03]: about_Parsing.md#passing-arguments-that-contain-quote-characters
+[04]: about_preference_variables.md#ofs
+[05]: about_Special_Characters.md
+[06]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData
diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md
@@ -1,7 +1,7 @@
 ---
 description: Describes rules for using single and double quotation marks in PowerShell.
 Locale: en-US
-ms.date: 09/04/2024
+ms.date: 09/09/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.4&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Quoting_Rules
@@ -34,6 +34,16 @@ command that are run on the remote computer. In a remote session, quotation
 marks also determine whether the variables in a command are interpreted first
 on the local computer or on the remote computer.
 
+> PowerShell treats smart quotation marks, also called typographic or curly
+> quotes, as normal quotation marks for strings. Don't use smart quotation
+> marks to enclose strings. When writing strings that contain smart quotation
+> marks, follow the guidance in the
+> [Including quote characters in a string](#including-quote-characters-in-a-string)
+> section of this document.
+>
+> For more information about smart quotation marks, see the _Smart Quotes_
+> section in the Wikipedia article [Quotation marks in English][02].
+
 ## Double-quoted strings
 
 A string enclosed in double quotation marks is an _expandable_ string. Variable
@@ -204,6 +214,20 @@ Use a quotation mark (") to begin a string.
 Use a quotation mark (`") to begin a string.
 ```
 
+Because PowerShell interprets smart quotation marks, like `‘`, `'`, `“`, and
+`”`, as normal quotation marks, smart quotation marks also need to be escaped.
+For example:
+
+```powershell
+"Double ““smart quotation marks`” must be escaped in a double-quoted string."
+'Single ‘‘smart quotation marks’’ must be escaped in a single-quoted string.'
+```
+
+```Output
+Double “smart quotation marks” must be escaped in a double-quoted string.
+Single ‘smart quotation marks’ must be escaped in a single-quoted string.
+```
+
 ## Here-strings
 
 The quotation rules for here-strings are slightly different.
@@ -360,7 +384,7 @@ see in the console.
 Collections, including arrays, are converted to strings by placing a single
 space between the string representations of the elements. A different separator
 can be specified by setting preference variable `$OFS`. For more information,
-see the [`$OFS` preference variable][03].
+see the [`$OFS` preference variable][04].
 
 Instances of any other type are converted to strings by calling the
 `ToString()` method, which may not give a meaningful representation. For
@@ -430,16 +454,17 @@ Some native commands expect arguments that contain quote characters. PowerShell
 interprets the quoted string before passing it to the external command. This
 interpretation removes the outer quote characters.
 
-For more information about this behavior, see the [about_Parsing][02] article.
+For more information about this behavior, see the [about_Parsing][03] article.
 
 ## See also
 
-- [about_Special_Characters][04]
-- [ConvertFrom-StringData][05]
+- [about_Special_Characters][05]
+- [ConvertFrom-StringData][06]
 
 <!-- link references -->
 [01]: about_Parsing.md#argument-mode
-[02]: about_Parsing.md#passing-arguments-that-contain-quote-characters
-[03]: about_preference_variables.md#ofs
-[04]: about_Special_Characters.md
-[05]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData
+[02]: https://en.wikipedia.org/wiki/Quotation_marks_in_English#Smart_quotes
+[03]: about_Parsing.md#passing-arguments-that-contain-quote-characters
+[04]: about_preference_variables.md#ofs
+[05]: about_Special_Characters.md
+[06]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData
diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md
@@ -1,7 +1,7 @@
 ---
 description: Describes rules for using single and double quotation marks in PowerShell.
 Locale: en-US
-ms.date: 09/04/2024
+ms.date: 09/09/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.5&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Quoting_Rules
@@ -34,6 +34,16 @@ command that are run on the remote computer. In a remote session, quotation
 marks also determine whether the variables in a command are interpreted first
 on the local computer or on the remote computer.
 
+> PowerShell treats smart quotation marks, also called typographic or curly
+> quotes, as normal quotation marks for strings. Don't use smart quotation
+> marks to enclose strings. When writing strings that contain smart quotation
+> marks, follow the guidance in the
+> [Including quote characters in a string](#including-quote-characters-in-a-string)
+> section of this document.
+>
+> For more information about smart quotation marks, see the _Smart Quotes_
+> section in the Wikipedia article [Quotation marks in English][02].
+
 ## Double-quoted strings
 
 A string enclosed in double quotation marks is an _expandable_ string. Variable
@@ -204,6 +214,20 @@ Use a quotation mark (") to begin a string.
 Use a quotation mark (`") to begin a string.
 ```
 
+Because PowerShell interprets smart quotation marks, like `‘`, `'`, `“`, and
+`”`, as normal quotation marks, smart quotation marks also need to be escaped.
+For example:
+
+```powershell
+"Double ““smart quotation marks`” must be escaped in a double-quoted string."
+'Single ‘‘smart quotation marks’’ must be escaped in a single-quoted string.'
+```
+
+```Output
+Double “smart quotation marks” must be escaped in a double-quoted string.
+Single ‘smart quotation marks’ must be escaped in a single-quoted string.
+```
+
 ## Here-strings
 
 The quotation rules for here-strings are slightly different.
@@ -360,7 +384,7 @@ see in the console.
 Collections, including arrays, are converted to strings by placing a single
 space between the string representations of the elements. A different separator
 can be specified by setting preference variable `$OFS`. For more information,
-see the [`$OFS` preference variable][03].
+see the [`$OFS` preference variable][04].
 
 Instances of any other type are converted to strings by calling the
 `ToString()` method, which may not give a meaningful representation. For
@@ -430,16 +454,17 @@ Some native commands expect arguments that contain quote characters. PowerShell
 interprets the quoted string before passing it to the external command. This
 interpretation removes the outer quote characters.
 
-For more information about this behavior, see the [about_Parsing][02] article.
+For more information about this behavior, see the [about_Parsing][03] article.
 
 ## See also
 
-- [about_Special_Characters][04]
-- [ConvertFrom-StringData][05]
+- [about_Special_Characters][05]
+- [ConvertFrom-StringData][06]
 
 <!-- link references -->
 [01]: about_Parsing.md#argument-mode
-[02]: about_Parsing.md#passing-arguments-that-contain-quote-characters
-[03]: about_preference_variables.md#ofs
-[04]: about_Special_Characters.md
-[05]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData
+[02]: https://en.wikipedia.org/wiki/Quotation_marks_in_English#Smart_quotes
+[03]: about_Parsing.md#passing-arguments-that-contain-quote-characters
+[04]: about_preference_variables.md#ofs
+[05]: about_Special_Characters.md
+[06]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData
