diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf075f5c0f25..cd24fefc9385 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,3 +7,4 @@ The following topics explain how to contribute to the PowerShell documentation. 1. [Get started](./contributing/GETSTARTED.md) 2. [Writing PowerShell documentation](./contributing/WRITING.md) 3. [Style Guide](./contributing/STYLE.md) +4. [Formatting code blocks](./contributing/FORMATTING-CODE.md). diff --git a/contributing/FORMATTING-CODE.md b/contributing/FORMATTING-CODE.md new file mode 100644 index 000000000000..2a3c43e6ff88 --- /dev/null +++ b/contributing/FORMATTING-CODE.md @@ -0,0 +1,171 @@ +# Formatting code blocks + +The existing documentation has used multiple styles, over time, and the formatting rules have changed multiple times. +We want to adopt a consistent style for PowerShell code blocks and output in our documentation. +The current Open Publishing System (OPS) we use has a syntax highlighting feature that supports many languages. +OPS also adds a **Copy** button that copies the contents of the code block to the clipboard. +This allows you to quickly paste the code into a script for testing the code example. +However, not all examples in our documentation are intended to be run. +Some code blocks are simple illustrations of a PowerShell concept. + +We are defining two scenarios for code blocks: + +1. Illustrative examples +2. Executable examples + +## Formatting illustrative examples + +Illustrative examples are used to explain a PowerShell concept. +They are not meant to be copied to the clipboard for execution. +These are most commonly used for simple examples that are easy to type. +They are also used for syntax examples where you are illustrating the syntax of a command. + +Illustrative examples use a "naked" code fence to mark the beginning and end of the code block. +The code block may contain example output from the command being illustrated. + +### Syntax block + +Here is an example of a syntax block: + + ``` + Get-Command [-Verb ] [-Noun ] [-Module ] + [-FullyQualifiedModule ] [-TotalCount ] [-Syntax] [-ShowCommandInfo] + [[-ArgumentList] ] [-All] [-ListImported] [-ParameterName ] + [-ParameterType ] [] + ``` + +This example illustrates all of the possible parameters of the `Get-Command` cmdlet. + +Here is another syntax example describing the `for` statement in generalized terms: + + ``` + for (; ; ) + {} + ``` + +### Simple illustration example + +Here is an example illustrating PowerShell comparison operators: + + ``` + PS> 2 -eq 2 + True + + PS> 2 -eq 3 + False + + PS> 1,2,3 -eq 2 + 2 + + PS> "abc" -eq "abc" + True + + PS> "abc" -eq "abc", "def" + False + + PS> "abc", "def" -eq "abc" + abc + ``` + +Note that this example has the simplified PowerShell prompt and shows the resulting output. +In this case, we don't intend the reader to copy this example and try to run the copied code. + +## Formatting executable examples + +More complex examples or examples that would be useful to copy and execute should use \`\`\`powershell\`\`\` code fence markers. +Output emitted by PowerShell commands should be enclosed in a **Output** code block to prevent syntax highlighting. + + For example: + + ```powershell + Get-Command -Module Microsoft.PowerShell.Security + ``` + + ```Output + CommandType Name Version Source + ----------- ---- ------- ------ + Cmdlet ConvertFrom-SecureString 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet ConvertTo-SecureString 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-Acl 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-Credential 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-PfxCertificate 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet New-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Protect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Set-Acl 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Set-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Set-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Test-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Unprotect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security + ``` + +The **Output** code label is not an official "language" supported by the syntax highlighting system. +However, this label is useful because OPS adds the "Output" label to the code box on the web page. +And this "Output" code box has no syntax highlighting. + +## Understanding the COPY button + +OPS also adds a **Copy** button that copies the contents of the code block to the clipboard. +This allows you to quickly paste the code into a script for testing the code example. +The **Copy** button also removes PowerShell prompts from the text before copying it to the clipboard. +The **Copy** button uses the following javascript code to remove the prompts. + +```javascript +if (language === 'powershell') { + text = text.replace(/\bPS [a-z]:\\>\s?/gi, ''); +} +``` + +Note that the regex used only matches simple prompts like "`PS C:\>`". +Prompts that include subdirectories or paths from other PSDrive providers will not be removed. +See the general guidelines, in the next section, for the appropriate use of prompts in examples. + +## General guidelines + +- Code fences + + Markdown allows for indentation to signify a code block, but this pattern can be problematic and should be avoided. + All code blocks should be contained in a code fence. + A code fence is a block of code surrounded by \`\`\` strings. + The code fence markers must be on their own line before and after the code sample. + The marker at the start of the code block may have an optional language label. + See the previous discussion about illustrative and executable examples for the proper use of language labels. + +- Line continuation in code samples + + Avoid using line continuation characters (\`) in PowerShell code examples. + These are hard to see and can cause problems if there are extra spaces on the end of the line. + Use PowerShell splatting to reduce line length for cmdlets that have a lot of parameters. + Take advantage of PowerShell's natural line break opportunities, like after pipe (\|) characters and opening braces, parentheses, and brackets. + +- PowerShell prompts in examples + + PowerShell prompts should only be used in illustrative examples. + Prompts should **NOT** be used in executable examples. + For most of these examples, the prompt string should be "`PS>`". + This prompt is independent of OS-specific indicators. + Use of the prompt string is discouraged and should be limited to scenarios that are meant to illustrate command line usage. + More complex prompt strings are required for examples that illustrate commands that alter the prompt + or when the path displayed is significant to the scenario being illustrated. + The following example illustrate how the prompt changes when using the Registry provider. + + ``` + PS C:\> cd HKCU:\System\ + PS HKEY_CURRENT_USER\System\> dir + + + Hive: HKEY_CURRENT_USER\System + + + Name Property + ---- -------- + CurrentControlSet + GameConfigStore GameDVR_Enabled : 1 + GameDVR_FSEBehaviorMode : 2 + Win32_AutoGameModeDefaultProfile : {2, 0, 1, 0...} + Win32_GameModeRelatedProcesses : {1, 0, 1, 0...} + GameDVR_HonorUserFSEBehaviorMode : 0 + GameDVR_DXGIHonorFSEWindowsCompatible : 0 + ``` diff --git a/contributing/STYLE.md b/contributing/STYLE.md index cef7671966eb..c17e3e0562a8 100644 --- a/contributing/STYLE.md +++ b/contributing/STYLE.md @@ -6,7 +6,7 @@ There are several variants of PowerShell. This table defines some of the different terms used to discuss PowerShell. | Terminology | Definition | -| ----- | -----| +| ----- | ----- | | PowerShell | This is the default. We are shipping PowerShell. The term PowerShell can be legitimately used to indicate any of the particular editions. This can be used to refer to the language, framework and default cmdlets, etc. | | PowerShell Core (PSCore) | PowerShell built on .NET Core Common Language Runtime (CoreCLR) for any of the platforms. | | Windows PowerShell | PowerShell built on .NET Common Language Runtime (CLR). Windows PowerShell ships only on Windows and requires the complete CLR. | @@ -84,43 +84,6 @@ Adding or removing H2 causes a build break. This [`Write-Host`](..\reference\6\Microsoft.PowerShell.Utility\Write-Host.md) cmdlet uses the **-Object** parameter to ... -## Formatting code blocks - -* All PowerShell syntax blocks should use \`\`\`powershell\`\`\` code fence markers. - -* Do **NOT** start PowerShell commands with the PowerShell prompt ("`PS C:\>`"). - -* Avoid using line continuation characters (\`) in PowerShell code examples. - These are a hard to see and can cause problems if there are extra spaces on the end of the line. - -* Output emitted by PowerShell commands should be enclosed in a naked code block to prevent it from recieving syntax highlighting. - - For example: - - ```powershell - Get-Command -Module Microsoft.PowerShell.Security - ``` - - ``` - CommandType Name Version Source - ----------- ---- ------- ------ - Cmdlet ConvertFrom-SecureString 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet ConvertTo-SecureString 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Get-Acl 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Get-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Get-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Get-Credential 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Get-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Get-PfxCertificate 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet New-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Protect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Set-Acl 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Set-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Set-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Test-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Unprotect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security - ``` - ## Lists * Do not end list items with a period (unless they contain multiple sentences) @@ -162,6 +125,10 @@ There are special rules for linking to reference topics from conceptual topics. \[TO DO\] - document special rules +## Next steps + +See [Formatting code blocks](FORMATTING-CODE.md). + [pascal-case]: https://en.wikipedia.org/wiki/PascalCase [issue1806]: https://github.com/PowerShell/PowerShell-Docs/issues/1806 diff --git a/dsc/docfx.json b/dsc/docfx.json index 6efaf25b9e83..723ddcc7b52b 100644 --- a/dsc/docfx.json +++ b/dsc/docfx.json @@ -20,7 +20,7 @@ "manager": "carmonm", "ms.devlang": "powershell", "ms.tgt_pltfr": "windows", - "ms.author": "eslesar" + "ms.author": "sewhee" }, "resource": [ { diff --git a/gallery/docfx.json b/gallery/docfx.json index 3b4663cfff20..7015d17719f4 100644 --- a/gallery/docfx.json +++ b/gallery/docfx.json @@ -18,8 +18,8 @@ "manager": "carmonm", "ms.devlang": "powershell", "ms.tgt_pltfr": "windows, macos, linux", - "author": "juanpablojofre", - "ms.author": "jpjofre" + "author": "JKeithB", + "ms.author": "keithb" }, "resource": [ { diff --git a/jea/docfx.json b/jea/docfx.json index eab8a2008c19..431b86b21360 100644 --- a/jea/docfx.json +++ b/jea/docfx.json @@ -18,7 +18,7 @@ "manager": "carmonm", "ms.devlang": "powershell", "ms.tgt_pltfr": "windows", - "ms.author": "jpjofre" + "ms.author": "sewhee" }, "resource": [ { diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/3.0/Microsoft.PowerShell.Utility/Get-Alias.md index d5cc83616c44..0d3b2fa3b993 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Get-Alias.md @@ -14,13 +14,15 @@ Gets the aliases for the current session. ## SYNTAX ### Default (Default) -``` -Get-Alias [[-Name] ] [-Exclude ] [-Scope ] [] +```powershell +Get-Alias [[-Name] ] [-Exclude ] [-Scope ] + [] ``` ### Definition -``` -Get-Alias [-Exclude ] [-Scope ] [-Definition ] [] +```powershell +Get-Alias [-Exclude ] [-Scope ] [-Definition ] + [] ``` ## DESCRIPTION @@ -139,19 +141,19 @@ Accept wildcard characters: True ``` ### -Name -Specifies the aliases to retrieve. +Specifies the aliases that this cmdlet gets. Wildcards are permitted. -By default, Get-Alias retrieves all aliases defined for the current session. -The parameter name ("Name") is optional. -You can also pipe alias names to Get-Alias. +By default, `Get-Alias` retrieves all aliases defined for the current session. +The parameter name **Name** is optional. +You can also pipe alias names to `Get-Alias`. ```yaml Type: String[] Parameter Sets: Default -Aliases: +Aliases: Required: False -Position: 1 +Position: 0 Default value: All aliases Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: True diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Select-Xml.md b/reference/3.0/Microsoft.PowerShell.Utility/Select-Xml.md index 1a383fcb6644..30edc8f4ddf8 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Select-Xml.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Select-Xml.md @@ -14,23 +14,27 @@ Finds text in an XML string or document. ## SYNTAX ### Xml (Default) -``` -Select-Xml [-Xml] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Xml] [-Namespace ] + [] ``` ### Path -``` -Select-Xml [-Path] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Path] [-Namespace ] + [] ``` ### LiteralPath -``` -Select-Xml -LiteralPath [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -LiteralPath [-Namespace ] + [] ``` ### Content -``` -Select-Xml -Content [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -Content [-Namespace ] + [] ``` ## DESCRIPTION @@ -214,7 +218,7 @@ Parameter Sets: Path Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: True @@ -231,7 +235,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -249,7 +253,7 @@ Parameter Sets: Xml Aliases: Node Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Set-TraceSource.md b/reference/3.0/Microsoft.PowerShell.Utility/Set-TraceSource.md index a9445e46eb7d..56ed0a2a9ac6 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Set-TraceSource.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Set-TraceSource.md @@ -102,20 +102,30 @@ Accept wildcard characters: False ``` ### -ListenerOption -Adds optional data to the prefix of each trace message in the output. -The valid values are "None", "LogicalOperationStack", "DateTime", "Timestamp", "ProcessId", "ThreadId", and "Callstack". -"None" is the default. +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: + +- None +- LogicalOperationStack +- DateTime +- Timestamp +- ProcessId +- ThreadId +- Callstack + +None is the default. To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "ProcessID,ThreadID". ```yaml Type: TraceOptions Parameter Sets: optionsSet -Aliases: +Aliases: +Accepted values: None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack Required: False Position: Named -Default value: "None" +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Trace-Command.md b/reference/3.0/Microsoft.PowerShell.Utility/Trace-Command.md index 9435adfbd072..4721f2eaf9af 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Trace-Command.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Trace-Command.md @@ -178,9 +178,18 @@ Accept wildcard characters: False ``` ### -ListenerOption -Adds optional data to the prefix of each trace message in the output. -The valid values are None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, and Callstack. -"None" is the default. +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: + +- None +- LogicalOperationStack +- DateTime +- Timestamp +- ProcessId +- ThreadId +- Callstack + +None is the default. To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "ProcessID,ThreadID". @@ -188,6 +197,7 @@ To specify multiple options, separate them with commas, but with no spaces, and Type: TraceOptions Parameter Sets: (All) Aliases: +Accepted values: None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack Required: False Position: Named diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/4.0/Microsoft.PowerShell.Utility/Get-Alias.md index 32666d375c1e..33741ff3cc8a 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Get-Alias.md @@ -16,13 +16,15 @@ Gets the aliases for the current session. ## SYNTAX ### Default (Default) -``` -Get-Alias [[-Name] ] [-Exclude ] [-Scope ] [] +```powershell +Get-Alias [[-Name] ] [-Exclude ] [-Scope ] + [] ``` ### Definition -``` -Get-Alias [-Exclude ] [-Scope ] [-Definition ] [] +```powershell +Get-Alias [-Exclude ] [-Scope ] [-Definition ] + [] ``` ## DESCRIPTION @@ -146,19 +148,19 @@ Accept wildcard characters: True ``` ### -Name -Specifies the aliases to retrieve. +Specifies the aliases that this cmdlet gets. Wildcards are permitted. -By default, Get-Alias retrieves all aliases defined for the current session. -The parameter name ("Name") is optional. -You can also pipe alias names to Get-Alias. +By default, `Get-Alias` retrieves all aliases defined for the current session. +The parameter name **Name** is optional. +You can also pipe alias names to `Get-Alias`. ```yaml Type: String[] Parameter Sets: Default -Aliases: +Aliases: Required: False -Position: 1 +Position: 0 Default value: All aliases Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: True diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Select-Xml.md b/reference/4.0/Microsoft.PowerShell.Utility/Select-Xml.md index 27dd86a4e05c..5d88cc4b07f2 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Select-Xml.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Select-Xml.md @@ -16,23 +16,27 @@ Finds text in an XML string or document. ## SYNTAX ### Xml (Default) -``` -Select-Xml [-Xml] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Xml] [-Namespace ] + [] ``` ### Path -``` -Select-Xml [-Path] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Path] [-Namespace ] + [] ``` ### LiteralPath -``` -Select-Xml -LiteralPath [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -LiteralPath [-Namespace ] + [] ``` ### Content -``` -Select-Xml -Content [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -Content [-Namespace ] + [] ``` ## DESCRIPTION @@ -222,7 +226,7 @@ Parameter Sets: Path Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: True @@ -239,7 +243,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -257,7 +261,7 @@ Parameter Sets: Xml Aliases: Node Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Set-TraceSource.md b/reference/4.0/Microsoft.PowerShell.Utility/Set-TraceSource.md index e2dc620f9ae1..32c4b0f0cf4a 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Set-TraceSource.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Set-TraceSource.md @@ -107,20 +107,30 @@ Accept wildcard characters: False ``` ### -ListenerOption -Adds optional data to the prefix of each trace message in the output. -The valid values are "None", "LogicalOperationStack", "DateTime", "Timestamp", "ProcessId", "ThreadId", and "Callstack". -"None" is the default. +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: + +- None +- LogicalOperationStack +- DateTime +- Timestamp +- ProcessId +- ThreadId +- Callstack + +None is the default. To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "ProcessID,ThreadID". ```yaml Type: TraceOptions Parameter Sets: optionsSet -Aliases: +Aliases: +Accepted values: None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack Required: False Position: Named -Default value: "None" +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Trace-Command.md b/reference/4.0/Microsoft.PowerShell.Utility/Trace-Command.md index 3feca7361691..4afcacb5117d 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Trace-Command.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Trace-Command.md @@ -183,9 +183,18 @@ Accept wildcard characters: False ``` ### -ListenerOption -Adds optional data to the prefix of each trace message in the output. -The valid values are None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, and Callstack. -"None" is the default. +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: + +- None +- LogicalOperationStack +- DateTime +- Timestamp +- ProcessId +- ThreadId +- Callstack + +None is the default. To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "ProcessID,ThreadID". @@ -193,6 +202,7 @@ To specify multiple options, separate them with commas, but with no spaces, and Type: TraceOptions Parameter Sets: (All) Aliases: +Accepted values: None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack Required: False Position: Named diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/5.0/Microsoft.PowerShell.Utility/Get-Alias.md index b98e54e4a55d..3a0dfb2d541b 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Get-Alias.md @@ -16,13 +16,15 @@ Gets the aliases for the current session. ## SYNTAX ### Default (Default) -``` -Get-Alias [[-Name] ] [-Exclude ] [-Scope ] [] +```powershell +Get-Alias [[-Name] ] [-Exclude ] [-Scope ] + [] ``` ### Definition -``` -Get-Alias [-Exclude ] [-Scope ] [-Definition ] [] +```powershell +Get-Alias [-Exclude ] [-Scope ] [-Definition ] + [] ``` ## DESCRIPTION @@ -148,20 +150,20 @@ Accept wildcard characters: False ### -Name Specifies the aliases that this cmdlet gets. Wildcards are permitted. -By default, **Get-Alias** retrieves all aliases defined for the current session. -The parameter name *Name* is optional. -You can also pipe alias names to **Get-Alias**. +By default, `Get-Alias` retrieves all aliases defined for the current session. +The parameter name **Name** is optional. +You can also pipe alias names to `Get-Alias`. ```yaml Type: String[] Parameter Sets: Default -Aliases: +Aliases: Required: False Position: 0 -Default value: None +Default value: All aliases Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Scope diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Select-Xml.md b/reference/5.0/Microsoft.PowerShell.Utility/Select-Xml.md index d148c2dee109..1ed9f4cbf757 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Select-Xml.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Select-Xml.md @@ -16,23 +16,27 @@ Finds text in an XML string or document. ## SYNTAX ### Xml (Default) -``` -Select-Xml [-Xml] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Xml] [-Namespace ] + [] ``` ### Path -``` -Select-Xml [-Path] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Path] [-Namespace ] + [] ``` ### LiteralPath -``` -Select-Xml -LiteralPath [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -LiteralPath [-Namespace ] + [] ``` ### Content -``` -Select-Xml -Content [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -Content [-Namespace ] + [] ``` ## DESCRIPTION diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Set-TraceSource.md b/reference/5.0/Microsoft.PowerShell.Utility/Set-TraceSource.md index 85e2f7b1414a..eebe12d65260 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Set-TraceSource.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Set-TraceSource.md @@ -107,7 +107,7 @@ Accept wildcard characters: False ``` ### -ListenerOption -Specifies optional data to add to the prefix of each trace message in the output. +Specifies optional data to the prefix of each trace message in the output. The acceptable values for this parameter are: - None @@ -125,7 +125,7 @@ To specify multiple options, separate them with commas, but with no spaces, and ```yaml Type: TraceOptions Parameter Sets: optionsSet -Aliases: +Aliases: Accepted values: None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack Required: False diff --git a/reference/5.1/Microsoft.PowerShell.Management/Stop-Process.md b/reference/5.1/Microsoft.PowerShell.Management/Stop-Process.md index db23cdff05dc..bc67d80cd668 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Stop-Process.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Stop-Process.md @@ -36,7 +36,7 @@ You can specify a process by process name or process ID (PID), or pass a process **Stop-Process** works only on processes running on the local computer. On Windows Vista and later versions of the Windows operating system, to stop a process that is not owned by the current user, you must start Windows PowerShell by using the Run as administrator option. -Also, you are will not be prompted for confirmation unless you specify the *Confirm* parameter. +Also, you are not prompted for confirmation unless you specify the *Confirm* parameter. ## EXAMPLES diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/5.1/Microsoft.PowerShell.Utility/Get-Alias.md index dbdaf6e0741b..9b7cea698f66 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Get-Alias.md @@ -16,13 +16,15 @@ Gets the aliases for the current session. ## SYNTAX ### Default (Default) -``` -Get-Alias [[-Name] ] [-Exclude ] [-Scope ] [] +```powershell +Get-Alias [[-Name] ] [-Exclude ] [-Scope ] + [] ``` ### Definition -``` -Get-Alias [-Exclude ] [-Scope ] [-Definition ] [] +```powershell +Get-Alias [-Exclude ] [-Scope ] [-Definition ] + [] ``` ## DESCRIPTION @@ -137,20 +139,20 @@ Accept wildcard characters: False ### -Name Specifies the aliases that this cmdlet gets. Wildcards are permitted. -By default, **Get-Alias** retrieves all aliases defined for the current session. -The parameter name *Name* is optional. -You can also pipe alias names to **Get-Alias**. +By default, `Get-Alias` retrieves all aliases defined for the current session. +The parameter name **Name** is optional. +You can also pipe alias names to `Get-Alias`. ```yaml Type: String[] Parameter Sets: Default -Aliases: +Aliases: Required: False Position: 0 -Default value: None +Default value: All aliases Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Scope diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Select-Xml.md b/reference/5.1/Microsoft.PowerShell.Utility/Select-Xml.md index d148c2dee109..1ed9f4cbf757 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Select-Xml.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Select-Xml.md @@ -16,23 +16,27 @@ Finds text in an XML string or document. ## SYNTAX ### Xml (Default) -``` -Select-Xml [-Xml] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Xml] [-Namespace ] + [] ``` ### Path -``` -Select-Xml [-Path] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Path] [-Namespace ] + [] ``` ### LiteralPath -``` -Select-Xml -LiteralPath [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -LiteralPath [-Namespace ] + [] ``` ### Content -``` -Select-Xml -Content [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -Content [-Namespace ] + [] ``` ## DESCRIPTION diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Set-TraceSource.md b/reference/5.1/Microsoft.PowerShell.Utility/Set-TraceSource.md index 3a159fa67a1a..12a086c65715 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Set-TraceSource.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Set-TraceSource.md @@ -107,7 +107,8 @@ Accept wildcard characters: False ``` ### -ListenerOption -Specifies optional data to add to the prefix of each trace message in the output.The acceptable values for this parameter are: +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: - None - LogicalOperationStack diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Trace-Command.md b/reference/5.1/Microsoft.PowerShell.Utility/Trace-Command.md index a61abffdee59..a2a243e10d0b 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Trace-Command.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Trace-Command.md @@ -183,7 +183,8 @@ Accept wildcard characters: False ``` ### -ListenerOption -Specifies optional data to the prefix of each trace message in the output.The acceptable values for this parameter are: +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: - None - LogicalOperationStack diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/6/Microsoft.PowerShell.Utility/Get-Alias.md index 7747dc402bdc..9b7cea698f66 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-Alias.md @@ -16,15 +16,15 @@ Gets the aliases for the current session. ## SYNTAX ### Default (Default) -``` -Get-Alias [[-Name] ] [-Exclude ] [-Scope ] [-InformationAction ] - [-InformationVariable ] [] +```powershell +Get-Alias [[-Name] ] [-Exclude ] [-Scope ] + [] ``` ### Definition -``` +```powershell Get-Alias [-Exclude ] [-Scope ] [-Definition ] - [-InformationAction ] [-InformationVariable ] [] + [] ``` ## DESCRIPTION @@ -136,50 +136,23 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -This parameter is called Definition, because it searches for the item name in the Definition property of the alias object.```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -This parameter is called Definition, because it searches for the item name in the Definition property of the alias object.```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Name Specifies the aliases that this cmdlet gets. Wildcards are permitted. -By default, **Get-Alias** retrieves all aliases defined for the current session. -The parameter name *Name* is optional. -You can also pipe alias names to **Get-Alias**. +By default, `Get-Alias` retrieves all aliases defined for the current session. +The parameter name **Name** is optional. +You can also pipe alias names to `Get-Alias`. ```yaml Type: String[] Parameter Sets: Default -Aliases: +Aliases: Required: False -Position: 1 -Default value: None +Position: 0 +Default value: All aliases Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Scope diff --git a/reference/6/Microsoft.PowerShell.Utility/Select-Xml.md b/reference/6/Microsoft.PowerShell.Utility/Select-Xml.md index 049b264b4022..68018279e772 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Select-Xml.md +++ b/reference/6/Microsoft.PowerShell.Utility/Select-Xml.md @@ -16,27 +16,27 @@ Finds text in an XML string or document. ## SYNTAX ### Xml (Default) -``` -Select-Xml [-Xml] [-XPath] [-Namespace ] - [-InformationAction ] [-InformationVariable ] [] +```powershell +Select-Xml [-XPath] [-Xml] [-Namespace ] + [] ``` ### Path -``` -Select-Xml [-Path] [-XPath] [-Namespace ] - [-InformationAction ] [-InformationVariable ] [] +```powershell +Select-Xml [-XPath] [-Path] [-Namespace ] + [] ``` ### LiteralPath -``` -Select-Xml -LiteralPath [-XPath] [-Namespace ] - [-InformationAction ] [-InformationVariable ] [] +```powershell +Select-Xml [-XPath] -LiteralPath [-Namespace ] + [] ``` ### Content -``` -Select-Xml -Content [-XPath] [-Namespace ] - [-InformationAction ] [-InformationVariable ] [] +```powershell +Select-Xml [-XPath] -Content [-Namespace ] + [] ``` ## DESCRIPTION @@ -203,33 +203,6 @@ Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` -### -InformationAction -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Namespace Specifies a hash table of the namespaces used in the XML. Use the format @{\ = \}. @@ -260,7 +233,7 @@ Parameter Sets: Path Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False @@ -277,7 +250,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -295,7 +268,7 @@ Parameter Sets: Xml Aliases: Node Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False diff --git a/reference/6/Microsoft.PowerShell.Utility/Set-TraceSource.md b/reference/6/Microsoft.PowerShell.Utility/Set-TraceSource.md index 2b255f16c570..d6850b719466 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Set-TraceSource.md +++ b/reference/6/Microsoft.PowerShell.Utility/Set-TraceSource.md @@ -137,7 +137,8 @@ Accept wildcard characters: False ``` ### -ListenerOption -Specifies optional data to add to the prefix of each trace message in the output.The acceptable values for this parameter are: +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: - None - LogicalOperationStack @@ -154,8 +155,8 @@ To specify multiple options, separate them with commas, but with no spaces, and ```yaml Type: TraceOptions Parameter Sets: optionsSet -Aliases: -Accepted values: None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, All +Aliases: +Accepted values: None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack Required: False Position: Named diff --git a/reference/6/Microsoft.PowerShell.Utility/Trace-Command.md b/reference/6/Microsoft.PowerShell.Utility/Trace-Command.md index cb751988bf9c..f4db42f35e2a 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Trace-Command.md +++ b/reference/6/Microsoft.PowerShell.Utility/Trace-Command.md @@ -183,7 +183,8 @@ Accept wildcard characters: False ``` ### -ListenerOption -Specifies optional data to the prefix of each trace message in the output.The acceptable values for this parameter are: +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: - None - LogicalOperationStack @@ -201,7 +202,7 @@ To specify multiple options, separate them with commas, but with no spaces, and Type: TraceOptions Parameter Sets: (All) Aliases: -Accepted values: None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, All +Accepted values: None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack Required: False Position: Named diff --git a/reference/docfx.json b/reference/docfx.json index 681ad61f080d..a8365f764236 100644 --- a/reference/docfx.json +++ b/reference/docfx.json @@ -238,8 +238,8 @@ "ms.topic": "reference", "manager": "carmonm", "ms.tgt_pltfr": "windows, macos, linux", - "author": "juanpablojofre", - "ms.author": "jpjofre" + "author": "sdwheeler", + "ms.author": "sewhee" }, "fileMetadata": {}, "template": [], diff --git a/reference/docs-conceptual/docfx.json b/reference/docs-conceptual/docfx.json index a95f0da40d0b..a557e8d563cb 100644 --- a/reference/docs-conceptual/docfx.json +++ b/reference/docs-conceptual/docfx.json @@ -16,8 +16,8 @@ "manager": "carmonm", "ms.devlang": "powershell", "ms.tgt_pltfr": "windows, macos, linux", - "author": "juanpablojofre", - "ms.author": "jpjofre" + "author": "sdwheeler", + "ms.author": "sewhee" }, "resource": [ { diff --git a/wmf/5.1/compatibility.md b/wmf/5.1/compatibility.md index e3225df9033b..4f5fdc3cbec4 100644 --- a/wmf/5.1/compatibility.md +++ b/wmf/5.1/compatibility.md @@ -32,3 +32,7 @@ The features of WMF 5.1 were included in Windows Server 2016 and Windows 10 Anni WMF 5.1 is not applicable for these operating system versions, as the updates are provided via Windows Update. +One thing to note is that WMF does not ship in Windows. +WMF is an upgrade package that provides a set of Windows features to previously released Windows versions. +This can make an important difference when seeking assistance for any of those features, as the version of those components will not match what shipped in the original operating system. + diff --git a/wmf/docfx.json b/wmf/docfx.json index a372afa1f7b3..baf309eb2474 100644 --- a/wmf/docfx.json +++ b/wmf/docfx.json @@ -14,11 +14,11 @@ "uhfHeaderId": "MSDocsHeader-Powershell", "ROBOTS": "INDEX, FOLLOW", "ms.prod": "powershell", - "ms.technology": "wmf", + "ms.technology": "", "manager": "carmonm", "ms.devlang": "powershell", "ms.tgt_pltfr": "windows", - "ms.author": "jpjofre" + "ms.author": "keithb" }, "resource": [ {