BZ#2018057: Clarify example opm command for updating SBI images

BZ2018057

4.6+

Due to customer confusion, this change clarifies the user-defined
variables in the example command for updating SQLite-based index images.

Author: michaelryanpeter

modules/olm-updating-index-image.adoc

@@ -35,20 +35,43 @@ endif::[]
 ----
 $ opm index add \
     --bundles <registry>/<namespace>/<new_bundle_image>@sha256:<digest> \//<1>
-    --from-index <registry>/<namespace>/<existing_index_image>:<tag> \//<2>
-    --tag <registry>/<namespace>/<existing_index_image>:<tag> \//<3>
-    --pull-tool podman <4>
+    --from-index <registry>/<namespace>/<existing_index_image>:<existing_tag> \//<2>
+    --tag <registry>/<namespace>/<existing_index_image>:<updated_tag> \//<3>
+    --pull-tool podman //<4>
+----
+<1> The `--bundles` flag specifies a comma-separated list of additional bundle images to add to the index.
+<2> The `--from-index` flag specifies the previously pushed index.
+<3> The `--tag` flag specifies the image tag to apply to the updated index image.
+<4> The `--pull-tool` flag specifies the tool used to pull container images.
++
+where:
++
+[small]
+--
+`<registry>`:: Specifies the hostname of the registry, such as `quay.io` or `mirror.example.com`.
+`<namespace>`:: Specifies the namespace of the registry, such as `ocs-dev` or `abc`.
+`<new_bundle_image>`:: Specifies the new bundle image to add to the registry, such as `ocs-operator`.
+`<digest>`:: Specifies the SHA image ID, or digest, of the bundle image, such as `c7f11097a628f092d8bad148406aa0e0951094a03445fd4bc0775431ef683a41`.
+`<existing_index_image>`:: Specifies the previously pushed image, such as `abc-redhat-operator-index`.
+`<existing_tag>`:: Specifies a previously pushed image tag, such as `pass:a[{product-version}]`.
+`<updated_tag>`:: Specifies the image tag to apply to the updated index image, such as `pass:a[{product-version}].1`.
+--
++
+.Example command
+[source,terminal,subs="attributes+"]
+----
+$ opm index add \
+    --bundles quay.io/ocs-dev/ocs-operator@sha256:c7f11097a628f092d8bad148406aa0e0951094a03445fd4bc0775431ef683a41 \
+    --from-index mirror.example.com/abc/abc-redhat-operator-index:{product-version} \
+    --tag mirror.example.com/abc/abc-redhat-operator-index:{product-version}.1 \
+    --pull-tool podman
 ----
-<1> A comma-separated list of additional bundle images to add to the index.
-<2> The existing index that was previously pushed.
-<3> The image tag that you want the updated index image to have.
-<4> A tool that pulls images for `opm index add`.
 
 . Push the updated index image:
 +
 [source,terminal]
 ----
-$ podman push <registry>/<namespace>/<existing_index_image>:<tag>
+$ podman push <registry>/<namespace>/<existing_index_image>:<updated_tag>
 ----
 
 ifeval::["{context}" == "olm-restricted-networks"]