Document docker transport is the only supported remote transport

The goal is to improve errors when users use the wrong transport
in certain cases we stutter, in other cases we don't give enough
information.

Remove stutters when failing to pull remote images, because of
lack of support.

Fix errors returned by reference.Parse to wrap in image that was being
checked.

Fixes: https://github.com/containers/podman/issues/7116

Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>

1 files changed, 23 insertions, 6 deletions

diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md
index 130c54ba9..4495cec3a 100644
--- a/docs/source/markdown/podman-pull.1.md
+++ b/docs/source/markdown/podman-pull.1.md
@@ -27,25 +27,42 @@ Images are stored in local image storage.
 ## SOURCE
 
  The SOURCE is the location from which the container images are pulled.
- The Image "SOURCE" uses a "transport":"details" format.
+ The Image "SOURCE" uses a "transport":"details" format.  Only the `docker` (container registry)
+ transport is allowed for remote access.
 
  Multiple transports are supported:
 
   **dir:**_path_
-  An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This is a non-standardized format, primarily useful for debugging or noninvasive container inspection.
+  An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This
+  is a non-standardized format, primarily useful for debugging or noninvasive container inspection.
 
-  **docker://**_docker-reference_
-  An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in `$XDG_RUNTIME_DIR/containers/auth.json`, which is set using `(podman login)`. If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using `(docker login)`.
+    $ podman pull dir:/tmp/myimage
+
+  **docker://**_docker-reference_ (Default)
+  An image reference stored in a remote container image registry. The reference can include a path to a
+  specific registry; if it does not, the registries listed in registries.conf will be queried to find a matching
+  image. By default, credentials from podman login (stored at $XDG_RUNTIME_DIR/containers/auth.json by default)
+  will  be used to authenticate; if these cannot be found, we will fall back to using credentials in
+  $HOME/.docker/config.json.
+
+    $ podman pull quay.io/username/myimage
 
   **docker-archive:**_path_[**:**_docker-reference_]
-  An image is stored in the `docker save` formatted file.  _docker-reference_ is only used when creating such a file, and it must not contain a digest.
+  An image is stored in the `docker save` formatted file.  _docker-reference_ is only used when creating such a
+  file, and it must not contain a digest.
+
+    $ podman pull docker-archive:/tmp/myimage
 
   **docker-daemon:**_docker-reference_
-  An image _docker-reference_ stored in the docker daemon internal storage.  _docker-reference_ must contain either a tag or a digest.  Alternatively, when reading images, the format can also be docker-daemon:algo:digest (an image ID).
+  An image in _docker-reference_ format stored in the docker daemon internal storage. The _docker-reference_ can also be an image ID (docker-daemon:algo:digest).
+
+    $ sudo podman pull docker-daemon:docker.io/library/myimage:33
 
   **oci-archive:**_path_**:**_tag_
   An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_.
 
+    $ podman pull oci-archive:/tmp/myimage
+
 ## OPTIONS
 
 #### **--all-tags**, **a**