System.CommandLine docs update

[adamsitnik]

High level overview:

1. I've merged the doc that explains the syntax (https://learn.microsoft.com/en-us/dotnet/standard/commandline/syntax) without showing the code and the doc that shows the related code (https://learn.microsoft.com/en-us/dotnet/standard/commandline/define-commands) into one.
2. I've moved the "Command-line design guidance" from syntax doc to a dedicated doc (it's big and important, but the very new users don't need to ready it when learning about syntax for the first time).
3. I've introduced a dedicated doc about how to parse and invoke to show it's two separate things.
4. I've introduced dedicated doc about other features such as parsing and validation etc
5. I've simplified the tutorial to start with a code that does not use invoking at all, just to show all its benefits and gradually use more features.

---

Internal previews

Toggle expand/collapse

📄 File	🔗 Preview link
docs/fundamentals/toc.yml	docs/fundamentals/toc
docs/standard/commandline/2.0.0-beta5.md	Breaking changes in System.CommandLine 2.0.0-beta5
docs/standard/commandline/command-line-configuration.md	How to configure the parser in System.CommandLine
docs/standard/commandline/design-guidance.md	Design guidance
docs/standard/commandline/get-started-tutorial.md	Tutorial: Get started with System.CommandLine
docs/standard/commandline/help.md	docs/standard/commandline/help
docs/standard/commandline/index.md	System.CommandLine overview
docs/standard/commandline/parse-and-invoke.md	"How to parse and invoke the result"
docs/standard/commandline/parsing-and-validation.md	How to customize parsing and validation in System.CommandLine
docs/standard/commandline/syntax.md	Syntax overview: Commands, options, and arguments
docs/standard/commandline/tab-completion.md	docs/standard/commandline/tab-completion

[gewarren]

Thanks for adding all these docs!

[gewarren]

Suggested change

	## Parse Errors
	## Parse errors

[gewarren]

Suggested change

	When there are multiple arguments, the order does matter. The following commands are not equivalent, they differ in the order of the values, which could lead to different results:
	When there are multiple arguments, the order does matter. The following commands are not equivalent; they differ in the order of the values, which could lead to different results:

[gewarren]

Suggested change

	`System.CommandLine` doesn't support automatic aliases, each alias needs to be specified in explicit way. Both commands and options expose `Aliases` property, but `Option` has a constructor that accepts aliases as parameters, so you can define an option with multiple aliases in a single line:
	`System.CommandLine` doesn't support automatic aliases. Each alias must be specified explicitly. Both commands and options expose an `Aliases` property. `Option` has a constructor that accepts aliases as parameters, so you can define an option with multiple aliases in a single line:

[gewarren]

Suggested change

	Both users and developers may find it useful to see how an app will interpret a given input. One of the default features of a `System.CommandLine` app is the `[diagram]` directive, which lets you preview the result of parsing command input. For example:
	Both users and developers might find it useful to see how an app will interpret a given input. One of the default features of a `System.CommandLine` app is the `[diagram]` directive, which lets you preview the result of parsing command input. For example:

[gewarren]

Suggested change

	* Add the appropriate shim script to your shell profile. You may need to create a shell profile file. The shim script forwards completion requests from your shell to the `dotnet-suggest` tool, which delegates them to the appropriate `System.CommandLine`-based app.
	* Add the appropriate shim script to your shell profile. You might need to create a shell profile file. The shim script forwards completion requests from your shell to the `dotnet-suggest` tool, which delegates them to the appropriate `System.CommandLine`-based app.

[adegeo]

It's really awesome to see some traction in this area, thanks you! Here are some improvements I found.

[adegeo]

Dates are MM/DD/YYYY

[adegeo]

I wouldn't name this file the version of the package, a new version means that a redirect has to be created and a file renamed. We also have a standard issue template for a "breaking change" doc, which we can use AI automation to generate details for. This article feels a little more like a "migration from beta 4 to beta 5" and would eventually go away.

[jeffhandley]

Great feedback! migration-guide-2.0.0-beta5.md perhaps?

[adegeo]

This isn't a how to, I would leave it blank for now.

Suggested change

ms.topic: how-to

[adegeo]

This article also isn't really a how to in the traditional sense. It just sort of plops a single snippet of code down and has some sub sections on what I assume are parameter options? But these descriptions don't really explain the options. For example, what does ResponseFileTokenReplacer actually do? Why would someone use it?

I would rewrite this to have a better "how to" approach:

• Configure the parser to do X
• Configure the parser to do Y
• Additional configuration options

[adegeo]

This seems like it should be more descriptive, perhaps this? Also, H1, not H2.

Suggested change

	## Help option
	# Customize help output

[adegeo]

This should move to live with the commandline docs docs/standard/commandline/includes/scl-preview.md

[adegeo]

I would have this opened up by default since it's the only collapsible child

Suggested change

	- name: How to
	items:
	- name: How to
	expanded: true
	items:

[adegeo]

I'm not sure why this is down at the bottom, would it make more sense to have it above the how to area?

[adegeo]

Is the version important? Can we just create a new .NET console app and things will work regardless? The previous release supported standard 2.0, is that still the case with beta 5? Does the code shown in here use some .NET 9-specific feature?

[adegeo]

Also, with all of these articles here under a How to section, if they're really how-to articles, it helps SEO if their file name is how-to-*.md.