Customize version style

[am11]

With the upcoming new standardization of name@version style in SDK dotnet/sdk#47980, these type of differences will be observed by the user in .NET 10:

# dotnet tool install
- dotnet tool install --global dotnet-ef --version 10.0.0-preview.3.25171.6
+ dotnet tool install --global [email protected]

# dotnet new template
- dotnet new install BenchmarkDotNet.Templates::0.14.0
+ dotnet new install [email protected]

# dotnet package add
- dotnet package add Newtonsoft.Json --version 13.0.3 --project .
+ dotnet package add [email protected] --project .

Currently, there is no idiomatic way to customize the usage line in command help. The workaround is to iterate over help section, skip the first line and overwrite it dotnet/sdk#47961 (comment), which is quite fragile as it can break if position of Usage is moved from index 1.

Proposal

One of these options may fit the current design:

1. Add a general purpose API to customize any predefined help section:

   public enum HelpSection { Description, Usage, Arguments }
   
   public class HelpBuilder
   {
       public void CustomizeSection(HelpSection section, Func<HelpContext, IEnumerable<Func<HelpContext, bool>>> sectionProducer);
   }
   // builder.CustomizeUsage(HelpSection.Usage, ctx => _ => { Console.WriteLine("dotnet tool install dotnet-ef[@version]"); return true; });

2. Add an API to customize the usage line:

   public class HelpBuilder
   {
       public void CustomizeUsage(Func<HelpContext, string> usageProducer);
   }
   // builder.CustomizeUsage(ctx => "dotnet tool install dotnet-ef[@version]");

3. Add an API explicitly for version style in usage:

   public class HelpBuilder
   {
       public void CustomizeUsageVersion(string joiner, bool optional);
   }
   // builder.CustomizeUsageVersion("@" /* or :: etc. */, false); // name@version
   // builder.CustomizeUsageVersion("@" /* or :: etc. */, true); // name[@version]

[am11]

cc @baronfel, @adamsitnik

[KalleOlaviNiemitalo]

Alternative 3 is not suitable. In this library, the --version option just shows the version of the application. The --version option that takes an argument to specify the version of a package to install is specific to .NET SDK. Moreover, if the command takes multiple arguments, the proposed API would not let the library know which of those arguments accepts a @version suffix.

For alternative 1, you can already use HelpBuilder.CustomizeLayout to replace HelpBuilder.Default.SynopsisSection() with a delegate that outputs whatever you want. This can be done by comparing delegates instead of relying on the order of sections (#1888). But then this delegate will also have to output the section heading itself, so you'll need to copy the translations of that heading to .NET SDK.

Do you want to hide the --version option from the synopsis section but not from the options section and not from command completion?

Do you want to display the @version suffix in the synopsis section but not in the arguments section?

[baronfel]

To me this is symptomatic of the S.CL parser not supporting mutually-exclusive symbols. If these symbols were supported then naturally you'd need to expand the default help reporting to show examples of the disparate groups.