Merge pull request #547 from Preeticp/callouts1

Modified title, hyphens, guidance, unordered list

Author: IngridT1

supplementary_style_guide/style_guidelines/formatting.adoc

@@ -51,23 +51,61 @@ default   active   yes         yes
 For commands and command outputs in code blocks, observe the correct markup for user-replaced values, as described in xref:user-replaced-values[] and xref:user-replaced-values-xml[].
 
 [[explain-commands-variables-in-code-blocks]]
-== Explain commands and variables in code blocks
+== Explanation of commands and variables used in code blocks
 
-To explain commands, lines of code, or variables (user-replaced values) used in a code block, follow the code block with the relevant explanation or description of the elements.
+To explain commands, lines of code, or user-replaced values in a code block, do not use callouts.
 
-. Use a simple sentence to explain or describe a single line of command, variable, option, or parameter.
+Instead, follow the code block with the relevant explanation or description of the elements, using the following guidelines:
+
+* Use a simple sentence to explain or describe a single line of command, variable, option, or parameter.
 +
 .Example AsciiDoc: A simple sentence explaining a single command
-+
+
 [source,terminal]
 ----
 $ hcp create cluster <platform> --help 
 ----
 +
 Use the `hcp create cluster` command to create and manage hosted clusters. The supported platforms are `aws`, `agent`, and `kubevirt`.
+
+* Use a definition list to explain multiple options, parameters, user-replaced values, placeholders, or UI elements.
+**  List the parameters or variables in the order in which they appear in the code block.
+**  Introduce definition lists with "where:" and begin each variable description with "Specifies".
++
+.Example AsciiDoc: A definition list explaining user-replaced values
+
+[source,yaml,subs="+attributes,+quotes"]
+----
+$ cat <<EOF | oc -n <my_product_namespace> create -f -
+apiVersion: v1
+kind: Secret
+metadata:
+ name: <my_product_database_certificates_secrets> 
+type: Opaque
+stringData:
+ postgres-ca.pem: |-
+  -----BEGIN CERTIFICATE-----
+  <ca_certificate_key> 
+ postgres-key.key: |-
+  -----BEGIN CERTIFICATE-----
+  <tls_private_key> 
+ postgres-crt.pem: |-
+  -----BEGIN CERTIFICATE-----
+  <tls_certificate_key> 
+  # ...
+EOF
+----
 +
-. Use a bulleted list to describe the structure of a sample YAML file or explain multiple lines of code in a code block.
+where:
+
+`<my_product_database_certificates_secrets>`:: Specifies the name of the certificate secret.
+`<ca_certificate_key>`:: Specifies the CA certificate key.
+`<tls_private_key>`:: Specifies the TLS private key.
+`<tls_certificate_key>`:: Specifies the TLS certificate key.
+
+* Use a bulleted list to describe the structure of a sample YAML file or explain multiple lines of code in a code block.
 **  List the explanations in the order in which they appear in the code block.
+** Use the bullet format that makes the most sense for your explanations. You do not have to follow the exact wording in the following example.
 +
 .Example AsciiDoc: A bulleted list explaining the structure of an YAML file
 
@@ -113,47 +151,10 @@ spec:
       - build-image
 ...
 ----
-
-* `workspaces`: List of pipeline workspaces shared between the tasks defined in the pipeline. A pipeline can define as many workspaces as required. In this example, only one workspace named `shared-workspace` is declared.
-* `tasks`: Definition of tasks used in the pipeline. This snippet defines two tasks, `build-image` and `apply-manifests`.
-* `tasks.name.workspaces`: List of task workspaces used in the `build-image` and `apply-manifests` tasks. A task definition can include as many workspaces as it requires. However, it is recommended that a task uses at most one writable workspace. In this example, both the tasks share a common task workspace named `source`, which in turn shares the pipeline workspace named `shared-workspace`.
-
-. Use a definition list to explain multiple options, parameters, variables, placeholders, or UI elements.
-**  List the parameters/variables in the order in which they appear in the code block.
-**  Introduce definition lists with "where:" and begin each variable description with "Specifies".
-+
-.Example AsciiDoc: A definition list explaining user-replaced values
-
-[source,yaml,subs="+attributes,+quotes"]
-----
-cat <<EOF | oc -n {my-product-namespace} create -f -
-apiVersion: v1
-kind: Secret
-metadata:
- name: <my-product-database-certificates-secrets> 
-type: Opaque
-stringData:
- postgres-ca.pem: |-
-  -----BEGIN CERTIFICATE-----
-  <ca-certificate-key> 
- postgres-key.key: |-
-  -----BEGIN CERTIFICATE-----
-  <tls-private-key> 
- postgres-crt.pem: |-
-  -----BEGIN CERTIFICATE-----
-  <tls-certificate-key> 
-  # ...
-EOF
-----
 +
-where:
-
-<my-product-database-certificates-secrets>:: Specifies the name of the certificate secret.
-<ca-certificate-key>:: Specifies the CA certificate key.
-<tls-private-key> Optional:: Specifies the TLS private key.
-<tls-certificate-key> Optional:: Specifies the TLS certificate key.
-
-. Use the appropriate admonition style to add notes pertaining to a code block, as described in xref:admonitions[]. 
+*** `spec.workspaces` defines the list of pipeline workspaces shared between the tasks defined in the pipeline. A pipeline can define as many workspaces as required. In this example, only one workspace named `shared-workspace` is declared.
+*** `spec.tasks` defines the tasks used in the pipeline. This snippet defines two tasks, `build-image` and `apply-manifests`.
+*** `spec.tasks.workspaces` defines the list of task workspaces used in the `build-image` and `apply-manifests` tasks. A task definition can include as many workspaces as it requires. However, it is recommended that a task uses at most one writable workspace. In this example, both the tasks share a common task workspace named `source`, which in turn could share the pipeline workspace named `shared-workspace`.
 
 [[date-formats]]
 == Date formats