Reorganize help layout

[jonsequitur]

There's some inconsistency in certain elements of the help layout as things have been added over time, and it deserves an update.

This issue is to discuss what a revised help layout should look like.

Related: #1157, #1168

[jonsequitur]

To start the conversation, here's an example based on a slightly fictionalized version of dotnet-interactive for illustration purposes:

Old:

Usage:
  dotnet-interactive jupyter [options] <connection-file> [<api-version>] [command]

Arguments:
  <1|2>                                  The API version [default: 2]
  <connection-file>                      The path to a connection file provided by Jupyter

Options:
  --default-kernel <default-kernel>      The default language for the kernel [default: csharp]
  --http-port-range <http-port-range>    Specifies the range of ports to use to enable HTTP
                                         services [default: 1000-3000]
  --log-format <JSON|PlainText>          Specify a log format
  --log-path <log-path>                  Enable file logging to the specified directory
  --verbose                              Enable verbose logging to the console
  -?, -h, --help                         Show help and usage information

Commands:
  install    Install the .NET kernel for Jupyter

New:

Usage:
  dotnet-interactive jupyter [options] <connection-file> [<api-version>]
  dotnet-interactive jupyter [options] [command [options]]

Arguments:
  <api-version>                          The API version [default: 2]
      allowed: 1|2
      default: 2
  <connection-file>                      The path to a connection file provided by Jupyter

Options:
  --default-kernel <default-kernel>      The default language for the kernel
      default: csharp
  --http-port-range <http-port-range>    Specifies the range of ports to use to enable HTTP
                                         services
      default: 1000-3000
  --log-format <format>                  Specify a log format
      allowed: JSON|PlainText
  --log-path <log-path>                  Enable file logging to the specified directory
  --verbose                              Enable verbose logging to the console
  -?, -h, --help                         Show help and usage information

Commands:
  install    Install the .NET kernel for Jupyter

There are a few changes worth considering.

• The "allowed" and "default" values are more explicitly called out, placed closer together, and are separate from the argument names. This is an addition to the existing argument descriptions, and a slight change to the existing option descriptions, where previously the presence of allowed values overrode the (mostly-uninteresting) argument name.

• The synopsis becomes two lines to represent different alternatives. (This one might be extremely difficult to do, but if it's sufficiently useful, it's worth discussing.)

[skrysmanski]

There is also one little missing feature that sneaked into you example: wrapping and aligning of long help texts. It would be really nice if this could also be implemented through this issue.

[jonsequitur]

We do have some degree of wrapping right now, but it might not be throughout. If you have a specific example of where wrapping can be improved, let's open an issue for it.

For reference, here's the same help requested at two different terminal widths:

[skrysmanski]

@jonsequitur Hmm, your examples look exactly like what I would expect. I have to check why my output didn't look like this in my project.

[skrysmanski]

@jonsequitur Ok, I figured it out. The problem comes from this method:

command-line-api/src/System.CommandLine/Help/HelpBuilder.cs

Lines 831 to 841 in 98a466e

	private int GetConsoleWindowWidth(IConsole console)
	{
	if (console is SystemConsole systemConsole)
	{
	return systemConsole.GetConsoleWindowWidth();
	}
	else
	{
	return int.MaxValue;
	}
	}

In my application, I'm setting my own IConsole instance. Unfortunately, the method GetConsoleWindowWidth() is not part of IConsole and thus I don't have properly aligned help text.

Do you want me to open a separate issue for this problem?

[jonsequitur]

Yes, please!

[skrysmanski]

@jonsequitur I've created #1184 for this.

[jonsequitur]

Thanks!