Powershell: Get-Help -Example should put a space after '>' and shouldn't use a Windows path on Unix

[mklement0]

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

• C:\ is used even on Unix-like platforms.

• A space is missing after the > char.

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)

[BrucePay]

Hmm - the prompt string should probably just be 'PS >' in all cases. Showing the operation being done in the root of the file system on either *nix or Windows is undesirable..

[rkeithhill]

Eliminating the C:\ makes sense to me given the cross-platform support. But I do prefer the space after the >. Perhaps PS> foo bar or PS > foo bar?

[BrucePay]

I'll make it "PS > ". Does that work for everyone?

[mklement0]

My preference is for PS>  (space only _after_ the >, given that in real prompts there's no space (immediately) _before_ it) rather than PS > , but either way is an improvement.

[BrucePay]

@mklement0 I'm not sure what you mean by 'real prompt'.

[mklement0]

@BrucePay: I mean an actual prompt string used in an interactive session, as defined by the default prompt() function:

PS> Get-Content function:prompt

"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) ";
# ...

To paraphrase: in a non-nested session (without having customized the prompt function), you'll see:

PS {/path/to/current/filesystem-location}> #<-- cursor shows here, after '> '

On Windows, if C:\ happens to be the filesystem location: PS C:\> ; on Unix, if / happens to be the current filesystem location: PS />  (note the space _following_ the > in both instances).

Now, if we intend to remove the - incidental - filesystem path from our example prompt string, we get to _choose_ whether we get to keep the space _before_ the >, between the PS and the path.

In the interest of showing the prompt as a more readily recognizable _unit_ (a prefix), my preference is to use PS>  rather than PS > .