Placeholder (variable) text#
Placeholder text (also referred to as variable text or replaceable text) stands for an object whose specific name is unknown to us. Placeholders are included when documenting syntax for how a command or path should be constructed. Users supply the relevant value for the placeholder when using the command or syntax.
Placeholder text usually indicates the type of element that’s being represented. For example, directoryName would likely indicate the name of a directory.
Note
Placeholder text is distinct from environment variables.
Environment variables have established formats and names, such as
$account, and their values are set in the system by users and
used consistently. By contrast, a placeholder is given a relevant value
by the user at the time that the user runs the code or types the
path. For information about formatting environment variables, see
Text formatting.
When creating placeholder text, use the following guidelines.
Note
For specific information about showing placeholders for account information such as account numbers, usernames, passwords, and API keys, see Cloud account information.
Guidelines |
Example |
|---|---|
Within regular text, show placeholder text in italics. Within code samples, use the RST If you can’t apply text formatting to the code, enclose placeholders in punctuation that doesn’t have any other special use in the code. For example, use angle brackets or curly braces. Use a consistent convention throughout the documentation set. |
|
Use lowercase letters except when showing a multiple-word placeholder. To show a multiple-word placeholder, don’t separate the words with spaces or symbols. To distinguish the words in the placeholder, capitalize the first letter of each word after the first word (called camelCase). Don’t capitalize the first word. Note: Use lowercase and camelCase unless you have to follow the conventions of the programming language. For example, you might need to use underscores (account_ID) or all capitals (ACCOUNT_ID). |
password serverName apiKey tenantId |
In general, use one or more whole words to represent a placeholder. Don’t sacrifice clarity for brevity. Create placeholders that are descriptive and meaningful. |
device (instead of dev) installationDirectory (instead of installDir) mode (instead of ########) |
When explaining a placeholder, use the following guidelines.
Guidelines |
Example |
|---|---|
Avoid stand-alone clauses that begin with where. Instead, use a sentence. |
Use: https://dfw.bigdata.api.rackspacecloud.com/v1.0/yourAccountId/ yourAccountId is your actual account number, which is returned as part of the authentication service response. Avoid: https://dfw.bigdata.api.rackspacecloud.com/v1.0/yourAccountId/ where yourAccountId is your actual account number, which is returned as part of the authentication service response. |
If you need to explain two or more placeholders, use an unordered list. |
From a supported web browser, type the following URL: http://hostName:portNumber/ed/index.html The placeholders in the URL are defined as follows:
|
Show the placeholder in regular text with the same formatting that it’s shown in the path or code. For example, if you can show it in italics, use italics when explaining it. If you first show the placeholder in a code block and need to enclose it in angle brackets, show it in angle brackets and monospace when explaining it. |
Use: https://dfw.bigdata.api.rackspacecloud.com/v1.0/yourAccountId/ yourAccountId is your actual account number, which is returned as part of the authentication service response. Use: Run the following command, replacing
|