Update image-trust man with further comments

Signed-off-by: TomSweeneyRedHat <tsweeney@redhat.com>

After the last update, @mtrmac had some great suggestions which I've incorporated.
I've updated the G:oogle doc and have added this PR in case it's easier to see the diffs.

Signed-off-by: TomSweeneyRedHat <tsweeney@redhat.com>

1 files changed, 18 insertions, 12 deletions

diff --git a/docs/podman-image-trust.1.md b/docs/podman-image-trust.1.md
index 668fee0f3..819035040 100644
--- a/docs/podman-image-trust.1.md
+++ b/docs/podman-image-trust.1.md
@@ -14,19 +14,29 @@ podman\-trust - Manage container registry image trust policy
 REGISTRY[/REPOSITORY]
 
 # DESCRIPTION
-Manages which registries you trust as a source of container images based on its location.  The location is determined by the transport and the registry host of the image.  Using this container image `docker://docker.io/library/busybox` as an example, `docker` is the transport and `docker.io` is the registry host.
+Manages which registries you trust as a source of container images  based on its location.  The location is determined
+by the transport and the registry host of the image.  Using this container image `docker://docker.io/library/busybox`
+as an example, `docker` is the transport and `docker.io` is the registry host.
 
-The trust policy describes a registry scope (registry and/or repository).  This trust can use public keys for signed images.
+Trust is defined in **/etc/containers/policy.json** and is enforced when a user attempts to pull
+a remote image from a registry.  The trust policy in policy.json describes a registry scope (registry and/or repository) for the trust.  This trust can use public keys for signed images.
 
-Trust is defined in **/etc/containers/policy.json** and is enforced when a user attempts to pull an image from a registry that is managed by policy.json.
+The scope of the trust is evaluated from most specific to the least specific. In other words, a policy may be defined for an entire registry.  Or it could be defined for a particular repository in that registry. Or it could be defined down to a specific signed image inside of the registry.
 
-The scope of the trust is evaluated from most specific to the least specific. In other words, a policy may be defined for an entire registry.  Or it could be defined for a particular repository in that registry. Or it could be defined down to a specific signed image inside of the registry.  See below for examples.
+For example, the following list includes valid scope values that could be used in policy.json from most specific to the least specific:
+
+docker.io/library/busybox:notlatest
+docker.io/library/busybox
+docker.io/library
+docker.io
+
+If no configuration is found for any of these scopes, the default value (specified by using "default" instead of REGISTRY[/REPOSITORY]) is used.
 
 Trust **type** provides a way to:
 
 Whitelist ("accept") or
-Blacklist ("reject") registries.
-
+Blacklist ("reject") registries or
+Require signature (“signedBy”).
 
 Trust may be updated using the command **podman image trust set** for an existing trust scope.
 
@@ -36,10 +46,8 @@ Trust may be updated using the command **podman image trust set** for an existin
 
 **-f** **--pubkeysfile**
   A path to an exported public key on the local system. Key paths
-  will be referenced in policy.json. Any path may be used but the path
-  **/etc/pki/containers** is recommended. Options may be used multiple times to
-  require an image be signed by multiple keys. One of **--pubkeys** or
-  **--pubkeysfile** is required for the **signedBy** type.
+  will be referenced in policy.json. Any path to a file may be used but locating the file in **/etc/pki/containers** is recommended. Options may be used multiple times to
+  require an image be signed by multiple keys.  The **--pubkeysfile** option is required for the **signedBy** type.
 
 **-t** **--type**
   The trust type for this policy entry. Accepted values:
@@ -84,7 +92,5 @@ Display trust as JSON
 policy-json(5)
 
 # HISTORY
-
 January 2019, updated by Tom Sweeney (tsweeney at redhat dot com)
-
 December 2018, originally compiled by Qi Wang (qiwan at redhat dot com)