Document reserved aliases

docs/Reserved-Aliases.md

@@ -1,6 +1,107 @@
-The following are [reserved aliases](#reserved-aliases)  in template engine. They are applied to .NET SDK 7+.
+### Reference for dotnetcli.host.json
+Generally the name of parameter symbol is the long name and its first character is the short name. Prefixing long name with `--` as long alias and prefixing short name with `-` are the aliases for the parameter symbol listed in the template options.  
+With `dotnetcli.host.json` file we can change long alias and short alias of the template option and its visibility. `dotnetcli.host.json` is located at the same directory as template.json file. It has the following configuration.
+- symbolsInfo  
+It has a collection of the name of specified parameter symbol in template.json with corresponding long or short name to override original ones and the visibility of the template option.  
+   - longName
+   - shortName  
+   Empty means short alias should not be used.
+   - isHidden  
+   True if hiding the parameter in CLI.
+- usageExamples  
+It's an array of usage exmples. Currently it's not used and please track on issue [#3262](https://github.com/dotnet/templating/issues/3262).
 
-If reserved alias is used as the name of Parameter symbol, it will be prefixed with `param:` or `-p:` as template option when instantiating the template.
+The following examples are several cases when using `dotnetcli.host.json`.
+
+##### Examples
+Override original long alias `--TargetFrameworkOverride` with `--targetframework` and override short alias `-T` with `-tf`. And this template option is hidden in CLI help information.
+```
+{
+  "$schema": "http://json.schemastore.org/dotnetcli.host",
+  "symbolInfo": {
+    "TargetFrameworkOverride": {
+      "isHidden": "true",
+      "longName": "targetframework",
+      "shortName": "tf"
+    },
+  },
+  "usageExamples": [
+    "--targetframework net7.0",
+    "-fr net7.0"
+  ]
+}
+```
+
+If short name is not specified, short name is the first character of overridden long name. Long alias is `--targetframework` and short alias is `-t`.
+```
+{
+  "$schema": "http://json.schemastore.org/dotnetcli.host",
+  "symbolInfo": {
+    "TargetFrameworkOverride": {
+      "longName": "targetframework"
+    },
+  },
+  "usageExamples": [
+    "--targetframework net7.0",
+    "-t net7.0",
+  ]
+}
+```
+
+If short name is empty, there is no short alias for the template option. Long alias is `--targetframework`.
+```
+{
+  "$schema": "http://json.schemastore.org/dotnetcli.host",
+  "symbolInfo": {
+    "TargetFrameworkOverride": {
+      "longName": "targetframework",
+      "shortName": ""
+    },
+  },
+  "usageExamples": [
+    "--targetframework net7.0"
+  ]
+}
+```
+
+If long/short alias from overridden long/short name is reserved alias, long name will be prefixed with `--param:` instead and short name will be prefixed with `-p:` instead. Here long alias is `--param:package` and short alias is `-p:i`. Please see [Reserved Aliases](#reserved-aliases).
+```
+{
+  "$schema": "http://json.schemastore.org/dotnetcli.host",
+  "symbolInfo": {
+    "pack": {
+      "longName": "package",
+      "shortName": "i"
+    },
+  },
+  "usageExamples": [
+    "--param:package net7.0",
+    "-p:i net7.0"
+  ]
+}
+```
+
+If the name of a parameter symbol is duplicate with any long name specified in `dotnetcli.host.json`, the long name is taken by the symbol specified in `dotnetcli.host.json`. Assuming there are two parameter symbols with the name `TargetFrameworkOverride`, `targetframework` respectively, long alias and short alias of symbol `TargetFrameworkOverride` is `--targetframework` and `-t`, long alias and short alias of symbol `targetframework` is `--param:targetframework` and `-ta`. Note that short name `ta` is generated from the beginning of the symbol's name till the one which can form a unique short name for symbol `targetframework`.
+```
+{
+  "$schema": "http://json.schemastore.org/dotnetcli.host",
+  "symbolInfo": {
+    "TargetFrameworkOverride": {
+      "longName": "targetframework"
+    },
+  },
+  "usageExamples": [
+    "--targetframework net7.0",
+    "-t net7.0"
+  ]
+}
+```
+
+### Reserved Aliases
+The following are [reserved aliases](#list-of-reserved-aliases) in template engine. They are applied to .NET SDK 7+.
+
+If long alias is reserved alias, long name will be prefixed with `--param:` instead.  
+If short alias is reserved alias, short name will be prefixed with `-p:` instead.  
 ##### Example
     "symbols": {
         "package": {
@@ -15,9 +116,9 @@ If reserved alias is used as the name of Parameter symbol, it will be prefixed w
          }
     }
 When instantiating the template, for symbol `package` the template option is **`--param:package`** , and `-p` for short.
-For symbol `u` the template option is `--u`, but **`-p:u`** for short.
+For symbol `u` the template option is `--u`, and **`-p:u`** for short.
 
-#### Reserved Aliases
+#### List of Reserved Aliases
 |Alias|Description|
 |-|-|
 |create|Instantiates a template with given short name.|