Help layout improvements

[vlada-shubina]

Suggesting couple of improvements for help layout

1. In case the option has many suggestions, the first column in layout becomes wide and layout is not very readable. Consider some shortcuts for these case, example,
   Actual: --my-option <has|a|very|long|list|of|suggestions|which|does|not|fit|my|screen|with|description>
   Suggested: --my-option <has|a|very...> or --my-option <val> + list all possible values in descriptions etc.

2. Consider better representation when option default value is set to empty string.
   Actual: [default: ] which is confusing as might be read as no default value.
   Suggested [default:<empty>] or similar

[jonsequitur]

1. Suggested: --my-option <has|a|very...> or --my-option + list all possible values in descriptions etc.

This is the kind of scenario we added HelpBuilder.CustomizeSymbol for. Does it work for you? It's hard to know what someone will want here and I don't know if these kinds of cases are common enough to warrant additional API surface.

2. Consider better representation when option default value is set to empty string.

When the default value is an empty string, would it just be clearer to not show a default value at all?

[EricZimmerman]

it would be super useful to have a sample app built with all these features in it, so we can see what they look like, tweak them, etc. this is even more important as the API changes, etc. i know there are a few example apps, but they are super minimal

[jonsequitur]

We've started working on proper samples and documentation.

[vlada-shubina]

@jonsequitur thanks for hint, actually I haven't realized that usage of HelpBuilder.CustomizeSymbol is also possible after parser creation, this helps.

For first column, I need to know base value before making decision whether to customize or not, making GetFirstColumnText public will help. (also GetSecondColumnText).

Also GetSecondColumnText should probably not reapply customization here:

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

Lines 592 to 598 in 98dbbec

	else if (
	_customizationsBySymbol is { } &&
	_customizationsBySymbol.TryGetValue(symbol, out var customization) &&
	customization.GetSecondColumn?.Invoke(context) is { } descriptionValue)
	{
	yield return descriptionValue;
	}

as it was already applied here:

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

Lines 515 to 517 in 98dbbec

	var secondColumnText =
	customization?.GetSecondColumn?.Invoke(context) ??
	GetSecondColumnText(identifierSymbol, context);