updated spec

Signed-off-by: Patrick Zheng <patrickzheng@microsoft.com>

specs/commandline/sign.md

@@ -50,7 +50,7 @@ Flags:
   -p,  --password string            password for registry operations (default to $NOTATION_PASSWORD if not specified)
        --plugin string              signing plugin name. This is mutually exclusive with the --key flag
        --plugin-config stringArray  {key}={value} pairs that are passed as it is to a plugin, refer plugin's documentation to set appropriate values.
-       --signature string           output path of generated signature when signing a file (required if --file is set)
+       --signature string           output path of generated signature when signing a file, can only be used when --file is set
        --signature-format string    signature envelope format, options: "jws", "cose" (default "jws")
   -u,  --username string            username for registry operations (default to $NOTATION_USERNAME if not specified)
   -m,  --user-metadata stringArray  {key}={value} pairs that are added to the signature payload
@@ -171,12 +171,20 @@ Notation supports signing a file located in user's file system. The file's conte
 # Prerequisites:
 # A default signing key is configured using CLI "notation key"
 
+# Use flag "--file" to enable signing a file
+# The generated signature is saved at the same dir as the target file with name
+# <target_file>.sig
+notation sign --file <target_file_path>
+
 # Use flag "--file" to enable signing a file
 # Use flag "--signature" to specify path where the generated signature is stored
 notation sign --file --signature <signature_path> <target_file_path>
 ```
-An example of a successful signing:
+Examples of successful signing:
 ```console
+$ notation sign --file ./myFile.txt 
+Successfully signed ./myFile.txt, stored signature at ./myFile.sig
+
 $ notation sign --file --signature ./mySignature.sig ./myFile.txt 
 Successfully signed ./myFile.txt, stored signature at ./mySignature.sig
 ```

specs/commandline/verify.md

@@ -52,7 +52,7 @@ Usage:
 Flags:
        --allow-referrers-api         [Experimental] use the Referrers API to verify signatures, if not supported (returns 404), fallback to the Referrers tag schema
   -d,  --debug                       debug mode
-        --file                       enable verifying a file, if set, the reference argument is the file path or full URI reference of the file artifact in registry (required if --signature is set)
+       --file                        enable verifying a file, if set, the reference argument is the file path or full URI reference of the file artifact in registry (required if --signature is set)
   -h,  --help                        help for verify
        --insecure-registry           use HTTP protocol while connecting to registries. Should be used only for testing
        --max-signatures int          maximum number of signatures to evaluate or examine (default 100)
@@ -193,7 +193,7 @@ Successfully verified signature for localhost:5000/net-monitor@sha256:b94d27b993
 ### Verify an arbitrary file located in OCI-compliant registry
 A user wants to verify a file stored as an OCI artifact in an OCI-compliant registry.
 ```shell
-# Prerequisites: Signatures are stored in a registry referencing the file artifact
+# Prerequisites: Signatures are stored in the registry referencing the file artifact
 
 # Use flag "--file" to enable verifying a file
 notation verify --file localhost:5000/myFile@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
@@ -211,14 +211,13 @@ A verifier wants to verify a file against its signatures located in file system.
 Trust policy to be used follows the rule below:
 1. User MAY pass in a trust policy scope via `--scope` flag. The value MUST follow Notation's trust policy [spec](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#registry-scopes-constraints). If the user specified trust policy does not exist in Notation's `trustpolicy.json` (use command `notation policy show` to check existence), then
 the [global trust policy](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#registry-scopes-constraints) is used.
-2. If user ignores the `--scope` flag, then the trust policy with scope `file/<target_file_name>` will be used as default. If this trust policy does not exist in Notation's `trustpolicy.json` (use command `notation policy show` to check existence), then
-the [global trust policy](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#registry-scopes-constraints) is used.
+2. If user ignores the `--scope` flag, then the [global trust policy](https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#registry-scopes-constraints) is used as default.
 ```shell
 # Prerequisites: Both target file and signatures are stored in user's file system
 
 # Use flag "--file" to enable verifying a file
 # Use flag "--signature" to speicfy path where the signatures are stored
-# Trust policy with scope "file/myFile" is used, if it does not exist, the global trust policy is used
+# The global trust policy is used by default
 notation verify --file --signature ./mySignature1.sig --signature ./mySignature2.sig ./myFile.txt
 
 export NOTATION_EXPERIMENTAL=1