The 1st (non-blank) line following .EXAMPLE in comment-based help is reformatted by PowerShell in two ways:
-
If no ...> prefix is present, PS C:\> is automatically prepended.
-
Whatever follows the automatically added prefix - or a retained custom prefix - has leading whitespace stripped, resulting in lines such as PS C:\>foo bar.
However, PS C:\>foo bar should be PS C:\> foo bar (a single space after >) so as to align with PowerShell's default prompt string.
Additionally, the automatically prepended prompt string uses path C:\ even on Unix-like platforms, which is confusing.
As an side: Windows PowerShell v5.1 exhibits the no-space-after-> also with compiled cmdlets, whereas in PowerShell Core the problem only surfaces with advanced functions.
Steps to reproduce
function foo {
<#
.EXAMPLE
foo bar
#>
param()
}
Get-Help foo -Examples
Expected behavior
Windows:
NAME
foo
SYNOPSIS
-------------------------- EXAMPLE 1 --------------------------
PS C:\> foo bar
Unix:
NAME
foo
SYNOPSIS
-------------------------- EXAMPLE 1 --------------------------
PS /> foo bar
Actual behavior
All platforms:
NAME
foo
SYNOPSIS
-------------------------- EXAMPLE 1 --------------------------
PS C:\>foo bar
Environment data
PowerShell Core v6.0.2 on macOS 10.13.4
PowerShell Core v6.0.2 on Ubuntu 16.04.4 LTS
PowerShell Core v6.0.2 on Microsoft Windows 10 Pro (64-bit; Version 1709, OS Build: 16299.371)
Windows PowerShell v5.1.16299.251 on Microsoft Windows 10 Pro (64-bit; Version 1709, OS Build: 16299.371)
The 1st (non-blank) line following
.EXAMPLEin comment-based help is reformatted by PowerShell in two ways:If no
...>prefix is present,PS C:\>is automatically prepended.Whatever follows the automatically added prefix - or a retained custom prefix - has leading whitespace stripped, resulting in lines such as
PS C:\>foo bar.However,
PS C:\>foo barshould bePS C:\> foo bar(a single space after>) so as to align with PowerShell's default prompt string.Additionally, the automatically prepended prompt string uses path
C:\even on Unix-like platforms, which is confusing.As an side: Windows PowerShell v5.1 exhibits the no-space-after-
>also with compiled cmdlets, whereas in PowerShell Core the problem only surfaces with advanced functions.Steps to reproduce
Expected behavior
Windows:
Unix:
Actual behavior
All platforms:
C:\is used even on Unix-like platforms.A space is missing after the
>char.Environment data