Powershell: Enhance PowerShell full command line help

[iSazonov]

• [ ] #5780 We should show the full/short command line help in Bash style if a parameter is wrong.
• [x] #4989 We should reformat the help in Bash style:
  
  
  
  • sort parameter list in alphabetical order.
  
  
  • replace long header on powershell[.exe] [options]
  
  
• [x] #4989 We should add more examples in line of the help.
• [x] #5275 Add "To get help type Help or Help followed by the command name, such as: Help Get-Process" in PowerShell banner bottom.

The Issue consider command line only powershell -Help (in bash or cmd.exe).

[markekraus]

@iSazonov this is for the PowerShell binary, correct?

We should show the full command line help in Bash style if a parameter is wrong.

Most Linux commands show usage and how to obtain help (-h, --help, man, etc.) on incorrect parameters unless their usage is very simple. Full help leads to the previous command going off console. command history is not always a given in the Linux world. I would prefer short syntax help and how to obtain the full help when I use the wrong parameters.

[iSazonov]

@markekraus The Issue is for discussion to collect ideas. :-)

I like short help on error too. We mean an interactive session where typos is a common matter - full help will going to annoy.

[markekraus]

@iSazonov by "We mean an interactive session where typos is a common matter"
Do you mean an interactive session in PowerShell?

example:

c:\> Get-Service -Nmae Get-Command

Get-Service : A parameter cannot be found that matches parameter name 'Nmae'.
At line:1 char:13
+ Get-Service -Nmae Get-Command
+             ~~~~~

SYNTAX
    Get-Service [[-Name] <String[]>] [-ComputerName <String[]>] [-DependentServices] [-Exclude <String[]>] [-Include <String[]>] [-RequiredServices] [<CommonParameters>]

    Get-Service [-ComputerName <String[]>] [-DependentServices] [-Exclude <String[]>] [-Include <String[]>] [-RequiredServices] -DisplayName <String[]> [<CommonParameters>]

    Get-Service [-ComputerName <String[]>] [-DependentServices] [-Exclude <String[]>] [-Include <String[]>] [-InputObject <ServiceController[]>] [-RequiredServices] [<CommonParameters>]

For more help on Get-Service run:
Get-Help -Name Get-Service -Full

[iSazonov]

No, the Issue consider command line only powershell -h (in bash or cmd.exe). I updated the Issue desciption.

[markekraus]

Ok then. Something like this:

c:\> powershell -noloexisto
The argument '-noloexisto' is not recognized as the name of a script file. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

PowerShell[.exe] [-PSConsoleFile <file> | -Version <version>]
    [-NoLogo] [-NoExit] [-Sta] [-Mta] [-NoProfile] [-NonInteractive] [-Interactive]
    [-InputFormat {Text | XML}] [-OutputFormat {Text | XML}]
    [-WindowStyle <style>] [-EncodedCommand <Base64EncodedCommand>]
    [-ConfigurationName <string>]
    [-Command { - | <script-block> [-args <arg-array>]
                  | <string> [<CommandParameters>] } ]
    [-File <filePath> <args>] [-ExecutionPolicy <ExecutionPolicy>]

PowerShell[.exe] -Help | -? | /?

[iSazonov]

We can be very short and show only PowerShell[.exe] -Help | -? | /?.

[markekraus]

I personally like being shown the syntax. that way something like this

powershell -NoUserEnvironment

doesn't require me to read the full help to see that it was supposed to be

powershell -NoProfile

[iSazonov]

Users will most _often_ see this help when there are typos. For newbie "PowerShell[.exe] -Help" is good start.

[markekraus]

Syntax is useful for typos, IMO.

c:\> powershell -NoPrfoile
The argument '-NoPrfoile' is not recognized as the name of a script file. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

PowerShell[.exe] [-PSConsoleFile <file> | -Version <version>]
    [-NoLogo] [-NoExit] [-Sta] [-Mta] [-NoProfile] [-NonInteractive] [-Interactive]
    [-InputFormat {Text | XML}] [-OutputFormat {Text | XML}]
    [-WindowStyle <style>] [-EncodedCommand <Base64EncodedCommand>]
    [-ConfigurationName <string>]
    [-Command { - | <script-block> [-args <arg-array>]
                  | <string> [<CommandParameters>] } ]
    [-File <filePath> <args>] [-ExecutionPolicy <ExecutionPolicy>]

PowerShell[.exe] -Help | -? | /?

then I can easily compare what I typed versus what the correct parameter is. If I have to run the full help and my command goes off screen, I can't easily compare. I may have to scroll and depending on the console I'm working in. that can be either impossible or painful.

[SteveL-MSFT]

From my limited test of Linux commands it seems most complain about the unknown parameter and just tells how to get help. However, I'm not against showing just the syntax.

[iSazonov]

@mklement0 Could you please comment? Have you ideas?

[mklement0]

I agree that the must-have components are:

• an error message that is neither drowned out by other information nor scrolled off screen
• a generic tip on how to get help.

A concise syntax diagram can be helpful, but the emphasis is on _concise_ - such as in @markekraus's hypothetical example - whereas the current -? output would be too wordy.

I'm not sure if POSIX mandates the format response to invalid command syntax for compliant utilities; in practice, you get instances of error message only, error message + help tip, and syntax only.

Some examples:

# BSD ls (macOS)
$ ls -y
ls: illegal option -- y
usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]

# GNU ls
$ ls -y
ls: invalid option -- 'y'
Try 'gls --help' for more information.

# BSD grep
$ grep -y
usage: grep [-abcDEFGHhIiJLlmnOoqRSsUVvwxZ] [-A num] [-B num] [-C[num]]
    [-e pattern] [-f file] [--binary-files=value] [--color=when]
    [--context[=num]] [--directories=action] [--label] [--line-buffered]
    [--null] [pattern] [file ...]


# GNU grep
Usage: ggrep [OPTION]... PATTERN [FILE]...
Try 'ggrep --help' for more information.

[iSazonov]

I really don't like scrolling so based on samples above I still suggest start with

<error message>
For more information try 'powershell -h' or Online Help https://...

Online Help link can be useful for Web/Azure scenarios.

[SteveL-MSFT]

cc @joeyaiello @HemantMahawar for some opinions here