Dashes in the tool name in the "Name" section of tool docs?

[omajid]

The .NET Core tool docs sometimes include a dash in the command name (dotnet-vstest) and sometimes they dont (dotnet add package). Should they stick to one style?

$ head -13 ./docs/core/tools/dotnet-add-package.md | tail -4
## Name

`dotnet add package` - Adds or updates a package reference in a project file.

$ head -16 ./docs/core/tools/dotnet-vstest.md | tail -4
## Name

`dotnet-vstest` - Runs tests from the specified assemblies.

I am not sure what style this doc is trying to follow, but man pages, which are closely aligned, always use a dash. For example:

$ man git add
...
NAME
       git-add - Add file contents to the index

What should the style in these docs be?

See also dotnet/sdk#25709

cc @mairaw

[mairaw]

Adding @baronfel and @tdykstra since it's been a few years since I've worked on those docs.

We did create those docs following similar existing docs like git. There was a point where we did have hyphens in the doc titles for example, but we removed after getting feedback that it was confusing.

I'll let the new owners decide what style we should use and apply it consistently.

[baronfel]

I did a quick regex search across the markdown docs for the CLI tools and only 2 pages use the dash syntax - dotnet-vstest and dotnet-install. The dotnet-install page is for the actual script named dotnet-install(.sh|.ps1) so I'm fine excluding it from the discussion.

I think we should make dotnet-vstest use the space version of the name to bring it into alignment with the others (and to make the HTML-rendered pages remain clear for webpage viewers), and then in the SDK's man page generation scripts apply the necessary _ formatting to mitigate the lint warnings for Debian.