8000 Enhance PowerShell full command line help · Issue #4986 · PowerShell/PowerShell · GitHub
[go: up one dir, main page]
Skip to content

Enhance PowerShell full command line help #4986

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
3 of 4 tasks
iSazonov opened this issue Oct 3, 2017 · 14 comments · Fixed by #5780
Closed
3 of 4 tasks

Enhance PowerShell full command line help #4986

iSazonov opened this issue Oct 3, 2017 · 14 comments · Fixed by #5780
Assignees
@iSazonov
Labels
Issue-Enhancement the issue is more of a feature request than a bug Resolution-Fixed The issue is fixed. WG-Interactive-Console the console experience

Comments

@iSazonov
Copy link
Collaborator
iSazonov commented Oct 3, 2017 •
edited
Loading

The Issue consider command line only powershell -Help (in bash or cmd.exe).
@iSazonov iSazonov added WG-Interactive-Console the console experience Issue-Enhancement the issue is more of a feature request than a bug labels Oct 3, 2017
@markekraus
Copy link
Contributor

@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
Copy link
Collaborator Author
iSazonov commented Oct 3, 2017

@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
Copy link
Contributor
markekraus commented Oct 3, 2017 •
edited
Loading

@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

Sorry, something went wrong.

@iSazonov
Copy link
Collaborator Author
iSazonov commented Oct 3, 2017 •
edited
Loading

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

@markekraus
Copy link
Contributor

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 iSazonov mentioned this issue Oct 3, 2017
Merged
@iSazonov
Copy link
Collaborator Author
iSazonov commented Oct 3, 2017

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

@markekraus
Copy link
Contributor
markekraus commented Oct 3, 2017 •
edited
Loading

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
Copy link
Collaborator Author
iSazonov commented Oct 3, 2017

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

@iSazonov iSazonov self-assigned this Oct 3, 2017
@markekraus
Copy link
Contributor

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
Copy link
Member

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
Copy link
Collaborator Author
iSazonov commented Oct 4, 2017

@mklement0 Could you please comment? Have you ideas?

@mklement0
Copy link
Contributor

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
Copy link 8000
Collaborator Author
iSazonov commented Oct 4, 2017

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
Copy link
Member

cc @joeyaiello @HemantMahawar for some opinions here

@iSazonov iSazonov mentioned this issue Oct 30, 2017
Merged
@iSazonov iSazonov mentioned this issue Jan 3, 2018
Merged
5 tasks
@iSazonov iSazonov added the Resolution-Fixed The issue is fixed. label Feb 8, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@iSazonov iSazonov

Labels
Issue-Enhancement the issue is more of a feature request than a bug Resolution-Fixed The issue is fixed. WG-Interactive-Console < 4507 /a> the console experience
Projects
None yet
Milestone
No milestone
4 participants
@mklement0 @markekraus @SteveL-MSFT @iSazonov
0