From 2bd81850d5bcf8307f985e2245bbd65d3eab3bfc Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Mon, 2 May 2022 14:36:27 -0500 Subject: [PATCH 1/4] (GH-8777) Reword here-string section for clarity This commit rewords the section of About Quoting Rules for clarity by being more explicit about the opening and closing tags and their effect. --- .../About/about_Quoting_Rules.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) 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 index b7214a3ea5a7..e538242d3666 100644 --- 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: 04/26/2022 +ms.date: 05/02/2022 online version: https://docs.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 @@ -201,10 +201,13 @@ Use a quotation mark (`") to begin a string. The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation -marks are interpreted literally. A here-string can span multiple lines. All the -lines in a here-string are interpreted as strings even though they are not -enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string surrounded by at signs +(`@`) in which quotation marks are interpreted literally. A here-string spans +multiple lines and always ends with a newline before the closing mark (`@'` for +single-quoted or `@"` for double-quoted). The closing mark of a here-string must +always be the first text on a line. Every line between the opening and closing +marks of a here-string is interpreted as part of a single string even if they +aren't enclosed in quotation marks. Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by @@ -214,7 +217,7 @@ You can use here-strings for any text, but they are particularly useful for the following kinds of text: - Text that contains literal quotation marks -- Multiple lines of text, such as the text in an HTML or XML +- Multiple lines of text, such as the text in an HTML or XML block - The Help text for a script or function document A here-string can have either of the following formats, where `` @@ -237,11 +240,8 @@ Single-quotes: '@ ``` -In either format, the closing quotation mark must be the first character in -the line. - -A here-string contains all the text between the two hidden characters. In the -here-string, all quotation marks are interpreted literally. For example: +A here-string contains all the text between the opening and closing marks. In +the here-string, all quotation marks are interpreted literally. For example: ```powershell @" From 10a80c0faf451e6b37ba48ff4c10c99f8e721b87 Mon Sep 17 00:00:00 2001 From: "Michael T Lombardi (He/Him)" Date: Tue, 3 May 2022 13:45:21 -0500 Subject: [PATCH 2/4] Apply suggestions from review Co-authored-by: Sean Wheeler --- .../About/about_Quoting_Rules.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) 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 index e538242d3666..9c4ea7e06e79 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -202,12 +202,11 @@ Use a quotation mark (`") to begin a string. The quotation rules for here-strings are slightly different. A here-string is a single-quoted or double-quoted string surrounded by at signs -(`@`) in which quotation marks are interpreted literally. A here-string spans -multiple lines and always ends with a newline before the closing mark (`@'` for -single-quoted or `@"` for double-quoted). The closing mark of a here-string must -always be the first text on a line. Every line between the opening and closing -marks of a here-string is interpreted as part of a single string even if they -aren't enclosed in quotation marks. +(`@`). The opening and closing marks must be on their own line. Quotation marks +within a here-string are interpreted literally. A here-string spans multiple +lines and always ends with a newline before the closing mark. The closing mark of +a here-string must always be the first text on a line. Every line between the +opening and closing marks of a here-string is part of a single string. Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by @@ -240,6 +239,10 @@ Single-quotes: '@ ``` +> [!NOTE] +> The final newline character is part of the closing mark. It is not added to +> the here-string. + A here-string contains all the text between the opening and closing marks. In the here-string, all quotation marks are interpreted literally. For example: From c7d34d8299e4fa5f945d4a3ff4f19d94e4d14746 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Tue, 3 May 2022 13:55:57 -0500 Subject: [PATCH 3/4] (GH-8777) Rework info for clarity This commit reworks the list of distinguishing factors of a here-string into an unordered list to improve readability and clarify the info. --- .../About/about_Quoting_Rules.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) 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 index 9c4ea7e06e79..16f51da7fa97 100644 --- 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: 05/02/2022 +ms.date: 05/03/2022 online version: https://docs.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 @@ -202,11 +202,15 @@ Use a quotation mark (`") to begin a string. The quotation rules for here-strings are slightly different. A here-string is a single-quoted or double-quoted string surrounded by at signs -(`@`). The opening and closing marks must be on their own line. Quotation marks -within a here-string are interpreted literally. A here-string spans multiple -lines and always ends with a newline before the closing mark. The closing mark of -a here-string must always be the first text on a line. Every line between the -opening and closing marks of a here-string is part of a single string. +(`@`). Quotation marks within a here-string are interpreted literally. + +A here-string: + +- spans multiple lines +- begins with the opening mark followed by a newline +- ends with a newline followed by the closing mark +- includes every line between the opening and closing marks as part of a single + string Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by From bad27e21f27394daa72ef54552cc12d41f79f30d Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Tue, 3 May 2022 13:58:39 -0500 Subject: [PATCH 4/4] (GH-8777) Push changes to all versions --- .../About/about_Quoting_Rules.md | 27 ++++++++++++------- .../About/about_Quoting_Rules.md | 27 ++++++++++++------- .../About/about_Quoting_Rules.md | 27 ++++++++++++------- .../About/about_Quoting_Rules.md | 27 ++++++++++++------- 4 files changed, 68 insertions(+), 40 deletions(-) diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 401e1e4e4ffc..fb4d655588be 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.0/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: 04/26/2022 +ms.date: 05/03/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Quoting Rules @@ -201,10 +201,16 @@ Use a quotation mark (`") to begin a string. The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation -marks are interpreted literally. A here-string can span multiple lines. All the -lines in a here-string are interpreted as strings even though they are not -enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string surrounded by at signs +(`@`). Quotation marks within a here-string are interpreted literally. + +A here-string: + +- spans multiple lines +- begins with the opening mark followed by a newline +- ends with a newline followed by the closing mark +- includes every line between the opening and closing marks as part of a single + string Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by @@ -214,7 +220,7 @@ You can use here-strings for any text, but they are particularly useful for the following kinds of text: - Text that contains literal quotation marks -- Multiple lines of text, such as the text in an HTML or XML +- Multiple lines of text, such as the text in an HTML or XML block - The Help text for a script or function document A here-string can have either of the following formats, where `` @@ -237,11 +243,12 @@ Single-quotes: '@ ``` -In either format, the closing quotation mark must be the first character in -the line. +> [!NOTE] +> The final newline character is part of the closing mark. It is not added to +> the here-string. -A here-string contains all the text between the two hidden characters. In the -here-string, all quotation marks are interpreted literally. For example: +A here-string contains all the text between the opening and closing marks. In +the here-string, all quotation marks are interpreted literally. For example: ```powershell @" diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 6e28b8921dca..0d33acb729e6 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.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: 04/26/2022 +ms.date: 05/03/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Quoting Rules @@ -201,10 +201,16 @@ Use a quotation mark (`") to begin a string. The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation -marks are interpreted literally. A here-string can span multiple lines. All the -lines in a here-string are interpreted as strings even though they are not -enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string surrounded by at signs +(`@`). Quotation marks within a here-string are interpreted literally. + +A here-string: + +- spans multiple lines +- begins with the opening mark followed by a newline +- ends with a newline followed by the closing mark +- includes every line between the opening and closing marks as part of a single + string Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by @@ -214,7 +220,7 @@ You can use here-strings for any text, but they are particularly useful for the following kinds of text: - Text that contains literal quotation marks -- Multiple lines of text, such as the text in an HTML or XML +- Multiple lines of text, such as the text in an HTML or XML block - The Help text for a script or function document A here-string can have either of the following formats, where `` @@ -237,11 +243,12 @@ Single-quotes: '@ ``` -In either format, the closing quotation mark must be the first character in -the line. +> [!NOTE] +> The final newline character is part of the closing mark. It is not added to +> the here-string. -A here-string contains all the text between the two hidden characters. In the -here-string, all quotation marks are interpreted literally. For example: +A here-string contains all the text between the opening and closing marks. In +the here-string, all quotation marks are interpreted literally. For example: ```powershell @" 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 index bbcd750a0f36..8aad7e1d1642 100644 --- 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: 04/26/2022 +ms.date: 05/03/2022 online version: https://docs.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 @@ -201,10 +201,16 @@ Use a quotation mark (`") to begin a string. The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation -marks are interpreted literally. A here-string can span multiple lines. All the -lines in a here-string are interpreted as strings even though they are not -enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string surrounded by at signs +(`@`). Quotation marks within a here-string are interpreted literally. + +A here-string: + +- spans multiple lines +- begins with the opening mark followed by a newline +- ends with a newline followed by the closing mark +- includes every line between the opening and closing marks as part of a single + string Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by @@ -214,7 +220,7 @@ You can use here-strings for any text, but they are particularly useful for the following kinds of text: - Text that contains literal quotation marks -- Multiple lines of text, such as the text in an HTML or XML +- Multiple lines of text, such as the text in an HTML or XML block - The Help text for a script or function document A here-string can have either of the following formats, where `` @@ -237,11 +243,12 @@ Single-quotes: '@ ``` -In either format, the closing quotation mark must be the first character in -the line. +> [!NOTE] +> The final newline character is part of the closing mark. It is not added to +> the here-string. -A here-string contains all the text between the two hidden characters. In the -here-string, all quotation marks are interpreted literally. For example: +A here-string contains all the text between the opening and closing marks. In +the here-string, all quotation marks are interpreted literally. For example: ```powershell @" diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 7e569ee4212d..ed56981ae422 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.3/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: 04/26/2022 +ms.date: 05/03/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Quoting Rules @@ -201,10 +201,16 @@ Use a quotation mark (`") to begin a string. The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation -marks are interpreted literally. A here-string can span multiple lines. All the -lines in a here-string are interpreted as strings even though they are not -enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string surrounded by at signs +(`@`). Quotation marks within a here-string are interpreted literally. + +A here-string: + +- spans multiple lines +- begins with the opening mark followed by a newline +- ends with a newline followed by the closing mark +- includes every line between the opening and closing marks as part of a single + string Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by @@ -214,7 +220,7 @@ You can use here-strings for any text, but they are particularly useful for the following kinds of text: - Text that contains literal quotation marks -- Multiple lines of text, such as the text in an HTML or XML +- Multiple lines of text, such as the text in an HTML or XML block - The Help text for a script or function document A here-string can have either of the following formats, where `` @@ -237,11 +243,12 @@ Single-quotes: '@ ``` -In either format, the closing quotation mark must be the first character in -the line. +> [!NOTE] +> The final newline character is part of the closing mark. It is not added to +> the here-string. -A here-string contains all the text between the two hidden characters. In the -here-string, all quotation marks are interpreted literally. For example: +A here-string contains all the text between the opening and closing marks. In +the here-string, all quotation marks are interpreted literally. For example: ```powershell @"