improve error msg and updated spec

Signed-off-by: Patrick Zheng <[email protected]>

cmd/notation/plugin/install.go

@@ -58,7 +58,7 @@ func installCommand(opts *pluginInstallOpts) *cobra.Command {
 	command := &cobra.Command{
 		Use:     "install [flags] <--file|--url> <plugin_source>",
 		Aliases: []string{"add"},
-		Short:   "Install plugin",
+		Short:   "Install a plugin",
 		Long: `Install a plugin
 
 Example - Install plugin from file system:

cmd/notation/plugin/uninstall.go

@@ -87,7 +87,7 @@ func uninstallPlugin(command *cobra.Command, opts *pluginUninstallOpts) error {
 	}
 	mgr := plugin.NewCLIManager(dir.PluginFS())
 	if err := mgr.Uninstall(ctx, pluginName); err != nil {
-		return fmt.Errorf("failed to uninstall %s: %w", pluginName, err)
+		return fmt.Errorf("failed to uninstall plugin %s: %w", pluginName, err)
 	}
 	fmt.Printf("Successfully uninstalled plugin %s\n", pluginName)
 	return nil

specs/commandline/plugin.md

@@ -49,10 +49,10 @@ Usage:
 Flags:
   -d, --debug              debug mode
       --file               install plugin from a file on file system
-      --force              force the installation of a plugin
+      --force              force the installation of the plugin
   -h, --help               help for install
-      --sha256sum string   must match SHA256 of the plugin source
-      --url                install plugin from an HTTPS URL
+      --sha256sum string   must match SHA256 of the plugin source, required when "--url" flag is set
+      --url                install plugin from an HTTPS URL. The default plugin download timeout is 10 minutes
   -v, --verbose            verbose mode
 
 Aliases:
@@ -68,7 +68,9 @@ Usage:
   notation plugin uninstall [flags] <plugin_name>
 
 Flags:
+  -d, --debug         debug mode
   -h, --help          help for remove
+  -v, --verbose       verbose mode
   -y, --yes           do not prompt for confirmation
 Aliases:
   uninstall, remove, rm
@@ -80,7 +82,7 @@ Aliases:
 
 ### Install a plugin from file system
 
-Install a Notation plugin from file system. Plugin file supports `.zip` and `.tar.gz` format. The checksum validation is optional for this case. 
+Install a Notation plugin from file system. Plugin file supports `.zip`, `.tar.gz`, and single plugin executable file format. The checksum validation is optional for this case. 
 
 ```shell
 $ notation plugin install --file <file_path>
@@ -95,13 +97,13 @@ Successfully installed plugin <plugin name>, version <x.y.z>
 If the entered plugin checksum digest doesn't match the published checksum, Notation will return an error message and will not start installation.
 
 ```console
-Error: plugin installation failed: plugin checksum does not match user input. Expecting <sha256sum>
+Error: plugin installation failed: plugin sha256sum does not match user input. Expecting <sha256sum>
 ```
 
 If the plugin version is higher than the existing plugin, Notation will start installation and overwrite the existing plugin.
 
 ```console
-Successfully installed plugin <plugin name>, updated the version from <x.y.z> to <a.b.c>
+Successfully updated plugin <plugin name> from version <x.y.z> to <a.b.c>
 ```
 
 If the plugin version is equal to the existing plugin, Notation will not start installation and return the following message. Users can use a flag `--force` to skip plugin version check and force the installation.
@@ -113,7 +115,7 @@ Error: plugin installation failed: plugin <plugin-name> with version <x.y.z> alr
 If the plugin version is lower than the existing plugin, Notation will return an error message and will not start installation. Users can use a flag `--force` to skip plugin version check and force the installation.
 
 ```console
-Error: failed to install plugin: <plugin-name>. The installing plugin version <a.b.c> is lower than the existing plugin version <x.y.z>.
+Error: plugin installation failed: failed to install plugin <plugin-name>. The installing plugin version <a.b.c> is lower than the existing plugin version <x.y.z>.
 It is not recommended to install an older version. To force the installation, use the "--force" option.
 ```
 ### Install a plugin from URL
@@ -134,7 +136,7 @@ Upon successful execution, the plugin is uninstalled from the plugin directory.
 
 ```shell
 Are you sure you want to uninstall plugin "<plugin name>"? [y/n] y
-Successfully uninstalled <plugin_name> 
+Successfully uninstalled plugin <plugin_name> 
 ```
 
 Uninstall the plugin without prompt for confirmation.
@@ -147,7 +149,7 @@ If the plugin is not found, an error is returned showing the syntax for the plug
 
 ```shell
 Error: unable to find plugin <plugin_name>. 
-To view a list of installed plugins, use "notation plugin list"
+To view a list of installed plugins, use `notation plugin list`
 ```
 
 ### List installed plugins