Formatting placeholders

Key point: Wrap placeholders in a <var> element and use uppercase characters with underscore delimiters.

This page explains how to format placeholder variables in commands and code samples. For more information about formatting code, command-line syntax, and code samples, see the following links:

• Code in text
• Documenting command-line syntax
• Code samples

Placeholders in sample code and commands represent values that the user must replace when they use the sample input. Placeholders in example output can also represent other values that vary. In general, a placeholder has a descriptive name as a default value.

For example, the placeholder PROJECT_ID represents a project ID in sample code, commands, and example output. In example output, the placeholder HTTP_RESPONSE_CODE represents an HTTP response code; the reader is not expected to set this to a specific value.

Placeholder variables

There are several ways to format placeholder variables, depending on whether you're working in HTML or Markdown, or whether the placeholder is inline or in a code block. For details, see the following sections.

Placeholder variables in inline text

If your placeholder variables occur in a sentence, use the following formatting:

• In HTML, wrap placeholders in <code><var> elements, like this:

  <code><var>PLACEHOLDER_VARIABLE</var></code>

• In Markdown, wrap inline placeholders in backticks (`), and use an asterisk (*) before the first backtick and after the second one (*`PLACEHOLDER_VARIABLE`*).

Placeholder variables in code blocks

If your placeholder variables are in a block of code, use the following formatting:

• In HTML, wrap the code block in a <pre> element, and tag placeholders with <var> elements, like this:

  <pre class="devsite-click-to-copy">
  gcloud compute forwarding-rules create <var>FORWARDING_RULE_NAME</var> \
      --global | --region=<var>REGION</var> \
      --load-balancing-scheme=<var>LOAD_BALANCING_SCHEME</var> \
      --network=<var>NETWORK</var> \
      ...
  </pre>
        

• In Markdown, wrap the code block in a code fence (```). Inside a code fence, you can't apply formatting like bold or italic.

  ```
  PLACEHOLDER_VARIABLE
  ```
        

Placeholder variable text

Use uppercase characters with underscore delimiters.

For example, in HTML:

Not recommended:

• https://developers.google.com/<var>API-name</var>
• https://developers.google.com/<var>API_name</var>
• https://developers.google.com/<var>API name</var>
• https://developers.google.com/<var>api_name</var>
• https://developers.google.com/<var>api-name</var>
• https://developers.google.com/<var>apiName</var>

Recommended:

• https://developers.google.com/<var>API_NAME</var>
• https://developers.google.com/<var>METHOD_NAME</var>

And in Markdown:

Recommended:

• https://developers.google.com/*API_NAME*
• https://developers.google.com/*METHOD_NAME*

If the context in which your placeholder variables appear makes using uppercase characters with underscore delimiters a bad idea, use something else that makes sense to you, but be internally consistent.

Don't include possessive pronouns in placeholders.

Not recommended:

• https://developers.google.com/<var>MY_API_NAME</var>
• https://developers.google.com/<var>YOUR_API_NAME</var>

Note: You can mark up command-line syntax with brackets, braces, and ellipses. Don't put the brackets, braces, or ellipses in the <var> element.

Explaining placeholders

When you use a placeholder in text or code, include an explanation for the placeholder the first time you use it. If there are many steps and other placeholders after the first use of that placeholder, it's OK to explain it again.

In procedures, use the following order:

1. Tell the user what they're doing.
2. List the command.
3. Explain the placeholder.
4. Explain the command in more detail if necessary.
5. List any output if necessary.
6. Explain any output if necessary.

The following is an example of a command that uses a placeholder with an explanation of that placeholder:

<pre class="devsite-click-to-copy">
gcloud compute instances create <var>INSTANCE_NAME</var> \
    --metadata enable-guest-attributes=TRUE
</pre>

<p>Replace the following:</p>

<ul>
  <li><code><var>INSTANCE_NAME</var></code>: the name you want your new VM instance to have</li>
</ul>

Single placeholder

Use the following format for a single placeholder:

• Replace PLACEHOLDER with a description of what the placeholder represents.

Recommended:

1. Stream the build logs to the Google Cloud Console:

   gcloud builds log --stream=BUILD_ID

   Replace BUILD_ID with the ID of the WORKING build that you copied in the preceding step. The log stream terminates upon build completion. Messages are displayed that indicate that the final terraform-destroy build step is successful and that the build is done.

Two or more placeholders

Use the following format for two or more placeholders:

• Follow the command line with a descriptive list of the placeholder variables used in the command line. Explain what each placeholder represents even if the placeholder value is intuitive to you.
• Introduce this list with Replace the following:
• List the placeholders in the order in which they appear in the command line.
• Provide a description for each placeholder.

• Tag each placeholder with <code><var> elements, followed by a colon and lowercase letter; for example:

  <li><code><var>INSTANCE_NAME</var></code>: description</li>

Recommended:

1. In Cloud Shell, set the environment variables:

   export ONPREM_PROJECT=ON_PREM_PROJECT_NAME
       export ONPREM_ZONE=ZONE

   Replace the following:

   • ON_PREM_PROJECT_NAME: the Google Cloud project name for your on-premises project
   • ZONE: a Google Cloud zone that's close to your location

   When you end the Cloud Shell session, you lose these environment variables.

Placeholders in output

If you provide an output example, explain any placeholders that appear in sample output.

1. Use <var> elements to identify the placeholder text in the output.
2. Follow the example output with a list of the placeholders used in the example.
3. Introduce the list of placeholders with In this output:
4. List the placeholders in the order in which they appear in the example.
5. Provide a description for each placeholder.

6. Tag each placeholder with <code><var> elements, followed by a colon and lowercase letter; for example:

   <li><code><var>INSTANCE_NAME</var></code>: description</li>

For more information, see Output from commands.

Response

The output is similar to the following:

{
 "name": "operations/build/PROJECT_ID/OPERATION_ID",
 "metadata": {
  "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata",
  "build": {
   "id": "BUILD_ID",
   "status": "QUEUED",
   "createTime": "2019-09-20T15:55:29.353258929Z",
   "steps": [
    {
     "name": "gcr.io/compute-image-tools/gce_vm_image_import:release",
     "env": [
      "BUILD_ID=BUILD_ID"
     ],
     "args": [
      "-timeout=7056s",
      "-image_name=IMAGE_NAME",
      "-client_id=api",
      "-data-disk",
      "-source_file=SOURCE_FILE"
     ]
    }
   ],
   "timeout": "7200s",
   "projectId": "PROJECT_ID",
   "logsBucket": "gs://PROJECT_NUMBER.cloudbuild-logs.googleusercontent.com",
   "options": {
    "logging": "LEGACY"
   },
   "logUrl": "https://console.cloud.google.com/gcr/builds/BUILD_ID?project=PROJECT_NUMBER"
  }
 }
}

In this output:

• PROJECT_ID: the project ID for the project that the image was imported into
• OPERATION_ID: the ID of the import operation
• BUILD_ID: the ID of the build for the import operation
• IMAGE_NAME: the name of the image to be imported
• SOURCE_FILE: the URI for the image in Cloud Storage, for example, gs://my-bucket/my-image.vmdk
• PROJECT_NUMBER: the number for the import project