Powershell: Before 6.0.0 ships can we make Get-Help -full the default?

[rkeithhill]

On Linux, the man pages display their full content by default. I believe PowerShell should do the same. The number of times I use get-help (or the alias man) without the -Full parameter can be counted on 1 hand (actually probably 0 hands). I've always disliked the switch that was made to seriously abbreviate PowerShell help topics. It was too dumbed down.

So here's a chance to do the right thing and make the default output the full output. I think that is what both Linux and macOS users would expect.

A "Did you look at the help for the examples on how to use that command",
B "Yes, I didn't see any."
A "Oh, didn't you use the -Full parameter on help?"
B "Huh? You mean the help command didn't show me all the help?"
A "Nope."
B "WTF?"

[iSazonov]

Maybe Help function should ask about show full help?

[bergmeister]

Even on Windows, I found that Get-Help without an additional Parameter was not very helpful most of the times. I would welcome it if showed e.g. at least one of the examples and maybe the OUTPUTS section. I agree with @iSazonov that it would be useful to have a prompt that says something like Show More? Y/N

[SteveL-MSFT]

For 6.1.0, we intend to revisit the whole helpsystem as well as rendering. For 6.0.0, we could default to showing full help if that is more useful for the majority of the time.

[rkeithhill]

I would prefer the help system default to full help. I believe emitting full help on Linux and macOS is much less of an issue because these OSs have decent paging utilities (and those users know how to use those utilities).

BTW Windows SERIOUSLY needs a better paging utility than more.com which is like using stone knives and bear skins compared to using less. :-)

[SteveL-MSFT]

Paging is one of the things we'll resolve along with the updated helpsystem during 6.1.0 timeframe.

[iSazonov]

I mean that users are more likely to use Help function than Get-Help cmdlet. We could enhance the function and don't change the cmdlet until 6.1.0.

[SteveL-MSFT]

@iSazonov that's an option, however, if the majority of cases is that they answer 'y', it seems showing the full help when using help since it gets paged would also work

[RichardSiddaway]

Defaulting to showing the full help contents would be best - especially on Windows. I'd prefer to have everything and scroll through rather than have it paged. Paging just makes things slower and adds negative value.
I never understood why the default was to show a cut down version when the most useful parts are the examples and the parameter descriptions when you're trying to understand how to use a cmdlet.

[rkeithhill]

Paging just makes things slower and adds negative value.

@RichardSiddaway That's because the pager on Windows sucks. When you use something like less you can scroll line-by-line or by pages and you can search for terms. Searching a help topic like this is very handy.

I know some folks don't like this next feature but when you do quit the pager (yeah, yeah pressing q is a bit weird) the helpt text is gone from the buffer so you can see your last command without having to scroll.

Besides, folks on Linux and macOS will expect help to be paged just like man on those platforms pages its output.

[abaddon82]

I'm not sure what the plans for paging in regards to the help system are, but I'm more of the opinion that Powershell in general could use some sort of Out-Pager.

[joeyaiello]

@SteveL-MSFT and I just spoke on this in our @PowerShell/powershell-committee meeting (no quorum).

We agree wholeheartedly on a few points:

• paging should be the default on Linux/Mac
• -Full should be the default (especially given default paging)
• in the fullness of time, we should do something like an Out-Pager (even if it's just a wrapper on the default pager, similar to the implementation in Get-Command help | Format-List Definition)

We're a little less sure on:

• Whether Windows should also page by default. I'm torn: the help function pages by default, and people are always confused there, but more.com is also really...not good.
• Whether we should make the help function an alias, and have Get-Help and help do the same thing (whether that's paging or not paging).

Thoughts?

[rkeithhill]

I'm a bit less concerned about Get-Help on Windows. Personally I'd prefer -Full on Windows to be the default but I understand that Windows users might not like that. And I can use $PSDefaultParameterValues for my personal set up. I guess you could wait until Windows gets a better paging utility before making -Full be the default on Windows.

RE help as an alias vs a function - I like the current implementation where help is a function because on Windows I can override the function and replace more with less. :-) And folks might have a preference for a different paging utility especially on Linux/macOS. So having Get-Help not be paged by default gives me the ability to choose a pager e.g. Get-Help iwr | less.

BTW for that help function, maybe we could get a preference variable for the paging utility to use - perhaps $PSHelpPager? If not, I can continue to override the function. :-)

[iSazonov]

We can make the pager smarter to ask if we want to get full help.
In the case we could set paging default on all platforms for Help. I believe we should leave Get-Help "as is" if anybody want grab a help text in scripts. I haven't thought about it before, but I use Help fuction most often then Get-Help.

I'll remind that we're planning (1) remove HelpSystem from Engine and make it more flexible, (2) to use MD-based help - the pager must support Markdown (colouring?).

Personally, I most often prefer to use online help because for other product modules, I need not only a description of the cmdlet but also blogs, technology and product articles that are searched through the search engine.

[lzybkr]

@rkeithhill - The more function honors $env:PAGER and the help function just pipes to more, so there is no need to add $PSHelpPager or the like.

[rkeithhill]

Excellent! I forgot that more was a function. Good tip to know about. Thanks.

[RichardSiddaway]

I'd still prefer the -Full help to be the default and not paged on Windows.

[rkeithhill]

Seems like @RichardSiddaway request could be satisfied if the more function was tweaked a bit such that setting $env:PAGER to a null or empty string would bypass using a pager utility.

$env:PAGER = $null
help gps # would dump all of help at once to the console

[dragonwolf83]

Funny, I never used help only Get-Help. I'm so used to the cmdlets and the list that is shown in ISE that I forget the non-cmdlet stuff that is available. The fact they work differently bothers me though as there is no indication from the names that they are different implementations.

[HumanEquivalentUnit]

Dumping ten screensfull of plaintext, monochrome help into the scrollback feels archaic, compared to Get-Help -Online. Or even Get-Help -ShowWindow. Being in the scrollback means you can't type or try your command, even a good pager takes over the entire screen until you quit it.

Is there any way the default help could show you something you can reference while writing and trying commands?

[SteveL-MSFT]

@HumanEquivalentUnit the latter point about showing reference while still using the console is something we're looking to address during 6.1.0 timeframe.

[SteveL-MSFT]

@rkeithhill the problem is that $env:PAGER is $null by default unless explicitly set and if $null it defaults to more on Windows and less on non-Windows.

[rkeithhill]

Makes sense. I was going to suggest that folks could write a simple script:

# C:\no-pager.ps1
$input

and then set $env:PAGER = "C:\no-pager.ps1" but the more function is designed to only work with apps. :-( I guess the more function could be made to recognize a value of None but not sure if it's worth it.

[SteveL-MSFT]

Not a great solution, but people can always overwrite the more function

[SteveL-MSFT]

@PowerShell/powershell-committee reviewed this and is fine with showing the full help on all systems (Windows, macOS, Linux) and paging by default for help function and no changes to get-help (not paging). Longer term, we would like to have help be an alias of get-help instead of a function that has different behavior.

[rkeithhill]

OK so the current implementation in PR #5195 just needs to be modified to remove the (!$IsWindows -or (Test-Path env:PAGER)) part of the if condition, right?

[SteveL-MSFT]

@rkeithhill yes, I believe that should be sufficient