Merge pull request #11656 from MicrosoftDocs/main

1/9/2025 PM Publish

Author: Taojunshen

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

@@ -1,47 +1,47 @@
 ---
 description: Explains Data sections, which isolate text strings and other read-only data from script logic.
 Locale: en-US
-ms.date: 04/23/2019
+ms.date: 01/09/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_data_sections?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Data_Sections
 ---
 # about_Data_Sections
 
 ## Short description
-Explains Data sections, which isolate text strings and other read-only
+
+Explains `DATA` sections, which isolate text strings and other read-only
 data from script logic.
 
 ## Long description
 
-Scripts that are designed for PowerShell can have one or more Data sections
-that contain only data. You can include one or more Data sections in any
-script, function, or advanced function. The content of the Data section is
+Scripts that are designed for PowerShell can have one or more `DATA` sections
+that contain only data. You can include one or more `DATA` sections in any
+script, function, or advanced function. The content of the `DATA` section is
 restricted to a specified subset of the PowerShell scripting language.
 
 Separating data from code logic makes it easier to identify and manage both
 logic and data. It lets you have separate string resource files for text, such
 as error messages and Help strings. It also isolates the code logic, which
 facilitates security and validation tests.
 
-In PowerShell, the Data section is used to support script internationalization.
-You can use Data sections to make it easier to isolate, locate, and process
-strings that will be translated into many user interface (UI) languages.
+In PowerShell, you can use the `DATA` section to support script
+internationalization. You can use `DATA` sections to make it easier to isolate,
+locate, and process strings that can be translated into other languages.
 
-The Data section is a PowerShell 2.0 feature. Scripts with Data sections will
-not run in PowerShell 1.0 without revision.
+The `DATA` section was added in PowerShell 2.0 feature.
 
 ### Syntax
 
-The syntax for a Data section is as follows:
+The syntax for a `DATA` section is as follows:
 
-```
+```Syntax
 DATA [<variable-name>] [-supportedCommand <cmdlet-name>] {
     <Permitted content>
 }
 ```
 
-The Data keyword is required. It is not case-sensitive. The permitted content
+The `DATA` keyword is required. It isn't case-sensitive. The permitted content
 is limited to the following elements:
 
 - All PowerShell operators, except `-match`
@@ -65,28 +65,28 @@ is limited to the following elements:
   '@
   ```
 
-- Cmdlets that are permitted in a Data section. By default, only the
+- Cmdlets that are permitted in a `DATA` section. By default, only the
   `ConvertFrom-StringData` cmdlet is permitted.
-- Cmdlets that you permit in a Data section by using the `-SupportedCommand`
+- Cmdlets that you permit in a `DATA` section by using the `-SupportedCommand`
   parameter.
 
-When you use the `ConvertFrom-StringData` cmdlet in a Data section, you can
+When you use the `ConvertFrom-StringData` cmdlet in a `DATA` section, you can
 enclose the key-value pairs in single-quoted or double-quoted strings or in
 single-quoted or double-quoted here-strings. However, strings that contain
 variables and subexpressions must be enclosed in single-quoted strings or in
-single-quoted here-strings so that the variables are not expanded and the
-subexpressions are not executable.
+single-quoted here-strings so that the variables aren't expanded and the
+subexpressions aren't executable.
 
 ### -SupportedCommand
 
-The `-SupportedCommand` parameter allows you to indicate that a cmdlet or
-function generates only data. It is designed to allow users to include cmdlets
-and functions in a data section that they have written or tested.
+The **SupportedCommand** parameter allows you to indicate that a cmdlet or
+function generates only data. It's designed to allow users to include cmdlets
+and functions in a `DATA` section that they have written or tested.
 
-The value of `-SupportedCommand` is a comma-separated list of one or more
+The value of **SupportedCommand** is a comma-separated list of one or more
 cmdlet or function names.
 
-For example, the following data section includes a user-written cmdlet,
+For example, the following `DATA` section includes a user-written cmdlet,
 `Format-Xml`, that formats data in an XML file:
 
 ```powershell
@@ -96,16 +96,16 @@ DATA -supportedCommand Format-Xml
 }
 ```
 
-### Using a Data Section
+### Using a `DATA` Section
 
-To use the content of a Data section, assign it to a variable and use variable
+To use the content of a `DATA` section, assign it to a variable and use variable
 notation to access the content.
 
-For example, the following data section contains a `ConvertFrom-StringData`
+For example, the following `DATA` section contains a `ConvertFrom-StringData`
 command that converts the here-string into a hash table. The hash table is
 assigned to the `$TextMsgs` variable.
 
-The `$TextMsgs` variable is not part of the data section.
+The `$TextMsgs` variable isn't part of the `DATA` section.
 
 ```powershell
 $TextMsgs = DATA {
@@ -124,7 +124,8 @@ $TextMsgs.Text001
 $TextMsgs.Text002
 ```
 
-Alternately, you can put the variable name in the definition of the Data section. For example:
+Alternately, you can put the variable name in the definition of the `DATA`
+section. For example:
 
 ```powershell
 DATA TextMsgs {
@@ -200,12 +201,23 @@ DATA -supportedCommand Format-XML {
 
 ## See also
 
-- [about_Automatic_Variables](about_Automatic_Variables.md)
-- [about_Comparison_Operators](about_Comparison_Operators.md)
-- [about_Hash_Tables](about_Hash_Tables.md)
-- [about_If](about_If.md)
-- [about_Operators](about_Operators.md)
-- [about_Quoting_Rules](about_Quoting_Rules.md)
-- [about_Script_Internationalization](about_Script_Internationalization.md)
-- [ConvertFrom-StringData](xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData)
-- [Import-LocalizedData](xref:Microsoft.PowerShell.Utility.Import-LocalizedData)
+- [about_Automatic_Variables][01]
+- [about_Comparison_Operators][02]
+- [about_Hash_Tables][03]
+- [about_If][04]
+- [about_Operators][05]
+- [about_Quoting_Rules][06]
+- [about_Script_Internationalization][07]
+- [ConvertFrom-StringData][08]
+- [Import-LocalizedData][09]
+
+<!-- link references -->
+[01]: about_Automatic_Variables.md
+[02]: about_Comparison_Operators.md
+[03]: about_Hash_Tables.md
+[04]: about_If.md
+[05]: about_Operators.md
+[06]: about_Quoting_Rules.md
+[07]: about_Script_Internationalization.md
+[08]: xref:Microsoft.PowerShell.Utility.ConvertFrom-StringData
+[09]: xref:Microsoft.PowerShell.Utility.Import-LocalizedData

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

@@ -1,7 +1,7 @@
 ---
 description: Explains how to use the Split operator to split one or more strings into substrings.
 Locale: en-US
-ms.date: 03/30/2021
+ms.date: 01/09/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_split?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Split
@@ -161,8 +161,24 @@ Vanilla
 Strawberry-Blueberry
 ```
 
-Negative values are ignored.
+Negative values return the amount of substrings requested starting
+from the end of the input string.
 
+> [!NOTE]
+> Support for negative values was added in PowerShell 7.
+
+```powershell
+$c = "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune"
+$c -split ",", -5
+```
+
+```Output
+Mercury,Venus,Earth,Mars
+Jupiter
+Saturn
+Uranus
+Neptune
+```
 
 ### \<ScriptBlock\>
 
@@ -216,26 +232,17 @@ The RegexMatch options are:
   SimpleMatch.
 - **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit
   operator is specified.
-- **CultureInvariant**: Ignores cultural differences in language
-  when evaluating the delimiter. Valid only with RegexMatch.
-- **IgnorePatternWhitespace**: Ignores unescaped whitespace and
-  comments marked with the number sign (#). Valid only with
-  RegexMatch.
-- **Multiline**: Multiline mode forces `^` and `$` to match the beginning
-  end of every line instead of the beginning and end of the input string.
-- **Singleline**: Singleline mode treats the input string as a *SingleLine*.
-  It forces the `.` character to match every character (including newlines),
+- **CultureInvariant**: Ignores cultural differences in language when
+  evaluating the delimiter. Valid only with RegexMatch.
+- **IgnorePatternWhitespace**: Ignores unescaped whitespace and comments marked
+  with the hash character (`#`). Valid only with RegexMatch.
+- **Multiline**: Multiline mode forces `^` and `$` to match the beginning end
+  of every line instead of the beginning and end of the input string.
+- **Singleline**: Singleline mode treats the input string as a *SingleLine*. It
+  forces the `.` character to match every character (including newlines),
   instead of matching every character EXCEPT the newline `\n`.
-- **ExplicitCapture**: Ignores non-named match groups so that only
-  explicit capture groups are returned in the result list. Valid
-  only with RegexMatch.
-
-> [!NOTE]
-> SingleLine is the default behavior. Singleline and Multiline
-> cannot be used together with the options parameter. This was resolved in
-> PowerShell 6.0.
-> The work around is by using *Mode-Modifiers* in your regular expression.
-> You can read more about mode modifiers in [Regular Expression Options](/dotnet/standard/base-types/regular-expression-options)
+- **ExplicitCapture**: Ignores non-named match groups so that only explicit
+  capture groups are returned in the result list. Valid only with RegexMatch.
 
 ## UNARY and BINARY SPLIT OPERATORS
 
@@ -390,6 +397,19 @@ b
 c,d,e,f,g,h
 ```
 
+The following statement splits a string into three substrings
+starting from the end of the string.
+
+```powershell
+"a,b,c,d,e,f,g,h" -split ",", -3
+```
+
+```Output
+a,b,c,d,e,f
+g
+h
+```
+
 The following statement splits two strings into three substrings.
 (The limit is applied to each string independently.)
 
@@ -423,7 +443,7 @@ $a = @'
 $a -split "^\d", 0, "multiline"
 ```
 
-```output
+```Output
 
 The first line.
 

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

@@ -2,8 +2,8 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 12/12/2022
-online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertfrom-stringdata?view=powershell-5.1&WT.mc_id=ps-gethelp
+ms.date: 01/09/2025
+online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertfrom-stringdata?view=powershell-7.4&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: ConvertFrom-StringData
 ---
@@ -36,7 +36,7 @@ machine translation tools. That is, the cmdlet can interpret backslashes (`\`) a
 in the string data by using the
 [Regex.Unescape Method](/dotnet/api/system.text.regularexpressions.regex.unescape), instead of the
 PowerShell backtick character (`` ` ``) that would normally signal the end of a line in a script.
-Inside the here-string, the backtick character does not work. You can also preserve a literal
+Inside the here-string, the backtick character doesn't work. You can also preserve a literal
 backslash in your results by escaping it with a preceding backslash, like this: `\\`. Unescaped
 backslash characters, such as those that are commonly used in file paths, can render as illegal
 escape sequences in your results.
@@ -46,22 +46,22 @@ escape sequences in your results.
 ### Example 1: Convert a single-quoted here-string to a hash table
 
 This example converts a single-quoted here-string of user messages into a hash table. In a
-single-quoted string, values are not substituted for variables and expressions are not evaluated.
+single-quoted string, values aren't substituted for variables and expressions aren't evaluated.
 The `ConvertFrom-StringData` cmdlet converts the value in the `$Here` variable to a hash table.
 
 ```powershell
 $Here = @'
 Msg1 = The string parameter is required.
 Msg2 = Credentials are required for this command.
-Msg3 = The specified variable does not exist.
+Msg3 = The specified variable doesn't exist.
 '@
 ConvertFrom-StringData -StringData $Here
 ```
 
 ```Output
 Name                           Value
 ----                           -----
-Msg3                           The specified variable does not exist.
+Msg3                           The specified variable doesn't exist.
 Msg2                           Credentials are required for this command.
 Msg1                           The string parameter is required.
 ```
@@ -92,8 +92,8 @@ Name                           Disks.ps1
 
 The value of the **StringData** parameter is a here-string, instead of a variable that contains a
 here-string. Either format is valid. The here-string includes a comment about one of the strings.
-`ConvertFrom-StringData` ignores single-line comments, but the `#` character must be the first
-non-whitespace character on the line. All characters on the line after the `#` are ignored.
+`ConvertFrom-StringData` ignores single-line comments, but the hash character (`#`) must be the
+first non-whitespace character on the line.
 
 ### Example 3: Convert a string to a hash table
 
@@ -115,9 +115,9 @@ Top              Red
 To satisfy the condition that each key-value pair must be on a separate line, the string uses the
 PowerShell newline character (`` `n ``) to separate the pairs.
 
-### Example 4: Use ConvertFrom-StringData in the DATA section of a script
+### Example 4: Use in the `DATA` section of a script
 
-This example shows a `ConvertFrom-StringData` command used in the **DATA** section of a script.
+This example shows a `ConvertFrom-StringData` command used in the `DATA` section of a script.
 The statements below the **DATA** section display the text to the user.
 
 ```powershell
@@ -138,7 +138,7 @@ Text002          The $MyNotebook variable contains the name of the user's privat
 ```
 
 Because the text includes variable names, it must be enclosed in a single-quoted string so that the
-variables are interpreted literally and not expanded. Variables are not permitted in the **DATA**
+variables are interpreted literally and not expanded. Variables aren't permitted in the `DATA`
 section.
 
 ### Example 5: Use the pipeline operator to pass a string
@@ -151,7 +151,7 @@ and the result in the `$Hash` variable.
 $Here = @'
 Msg1 = The string parameter is required.
 Msg2 = Credentials are required for this command.
-Msg3 = The specified variable does not exist.
+Msg3 = The specified variable doesn't exist.
 '@
 $Hash = $Here | ConvertFrom-StringData
 $Hash
@@ -160,15 +160,15 @@ $Hash
 ```Output
 Name     Value
 ----     -----
-Msg3     The specified variable does not exist.
+Msg3     The specified variable doesn't exist.
 Msg2     Credentials are required for this command.
 Msg1     The string parameter is required.
 ```
 
 ### Example 6: Use escape characters to add new lines and return characters
 
 This example shows the use of escape characters to create new lines and return characters in source
-data. The escape sequence `\n` is used to create new lines within a block of text that is associated
+data. The escape sequence `\n` is used to create new lines within a block of text that's associated
 with a name or item in the resulting hash table.
 
 ```powershell
@@ -187,7 +187,7 @@ Value : Let there be some more test made of my metal,
 Name  : Vincentio
 Value : Heaven doth with us as we with torches do,
         Not light them for themselves; for if our virtues
-        Did not go forth of us, 'twere all alike
+        Didn't go forth of us, 'twere all alike
         As if we had them not.
 ```
 
@@ -218,10 +218,10 @@ The value of this parameter must be a string that contains one or more key-value
 key-value pair must be on a separate line, or each pair must be separated by newline characters
 (`` `n ``).
 
-You can include comments in the string, but the comments cannot be on the same line as a key-value
-pair. `ConvertFrom-StringData` ignores single-line comments. The `#` character must be the first
-non-whitespace character on the line. All characters on the line after the `#` are ignored. The
-comments are not included in the hash table.
+You can include comments in the string, but the comments can't be on the same line as a key-value
+pair. `ConvertFrom-StringData` ignores single-line comments. The hash character (`#`) must be the
+first non-whitespace character on the line. All characters on the line after the hash character
+(`#`) are ignored. The comments aren't included in the hash table.
 
 A here-string is a string consisting of one or more lines. Quotation marks within the here-string
 are interpreted literally as part of the string data. For more information, see