Make online help more prominent

[nohwnd]

Is your feature request related to a problem? Please describe.

dotnet sdk has extensive online help, and sparser commandline help. The online help can be opened by dotnet help <command> but nothing in the help suggests it. Even the help of the help command says it will show the command line help, not the online help.

PS> dotnet --help | Select-String help

  -h|--help         Show command line help.
  help              Show command line help.
Run 'dotnet [command] --help' for more information on a command.

On the bottom it suggests using dotnet command --help which opens the command line help and not the online help.

I think it would be nice to make the possibility to open online help more prominent, because I often look at the commandline help for quick reference, and then end up searching for the same thing online to land on Microsoft docs page.

Second part of my motivation is that specifically, for dotnet test we have some commandline help entries that are 10-20 lines. This is hard to read and we often fail to update the help. Having the commandline help show the link on the top, would allow us to reduce the amount of information we put in commandline help to the bare minimum needed for quick overview, while still telling the user how to learn more if needed.

Describe the solution you'd like

1. Add dotnet <command> --online-help parameter that opens the respective help page, as alternative to using dotnet help <command>. Possibly alias it as -?? and -oh.

2. Make online help listed in each help section so users using dotnet <command> --help can learn about the possibility to open online help.

PS> dotnet run --help
Description:
  .NET Run Command

+ See online help for full documentation: https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-run

Usage:
  dotnet run [options] [[--] <additional arguments>...]]
  
Options:
  -c, --configuration <CONFIGURATION>     The configuration to run for. The default for most projects is 'Debug'.
  -f, --framework <FRAMEWORK>             The target framework to run for. The target framework must also be specified in
[...]
    -?, -h, --help                          Show command line help.
+   -??, -oh, --online-help 	            Show online help.

Showing the link directly allows me to just click on it in Windows Terminal.

1. Suggest using help or online help in the dotnet --help section.

PS> dotnet --help 

+ Run 'dotnet [command] --help' or 'dotnet [command] --online-help' for more information on a command.

[baronfel]

I took a look at git, which also has this online-help capability (at least on Windows), and I noticed that their help output always advertises the 'rich' version. Specifically, where we have the line Run 'dotnet [command] --help' they would instead say Run 'dotnet help [command]'. Would this be sufficient for you? The existing --help flags would still exist for backwards compatibility and local-usage reasons, but we'd guide users to using the version of help that has more details by default.

[KalleOlaviNiemitalo]

dotnet help [command]

That could be extended to .NET global tools and then also local tools (dotnet tool help command) by reading an online help URL from a child element of the Command element in DotNetToolSettings.xml. However, if the tool has subcommands, then such a statically declared URL would not be able to support subcommand-specific online help, because the dotnet executable wouldn't know exactly how the tool parses its subcommands. For tools that use System.CommandLine or are otherwise compatible with its directive syntax, DotNetToolSettings.xml could alternatively declare support for an [onlinehelp] directive.

[nohwnd]

@baronfel I think the command line help is great for getting a quick overview of what is available. Often I know what I want to do, but don't remember the exact parameter name I need to use. And in that case the sparse help with just --some-param one-liner description, is very useful.

would instead say Run 'dotnet help [command]'

I am not sure if that is enough to let people know about it, but maybe it is a start and you have some metrics on the usage of dotnet help? I think listing the link on the top of the commandline help (or on the bottom in related links section, like powershell does it), would help a lot.

@KalleOlaviNiemitalo I would love this to become a widely available capability, with the link to onlinehelp specified at the command/sub-command level.

[KalleOlaviNiemitalo]

If a user runs dotnet commands or tools over SSH or a similar connection, I think having --help display the URL for the user to click or copy will work better than making --onlinehelp or dotnet help try to launch a Web browser in the remote computer, and it is trivial to implement too. Do devcontainers have a similar restriction?

(I'm a bit sad that all documentation is moving online. A spec for how to include detailed offline documentation in a .NET tool package, or link to a separate documentation package, would be cool. It's not the goal of this issue though.)