Text Formatting
You should add formatting to words, phrases, or blocks that require
emphasis. You can use one of the formatting options to convey emphasis:
weight (bold), variant (italics), or pitch (monospace
).
When formatting text, use the following guidelines:
To apply a font treatment, use the appropriate markup in your authoring tool. In reStructuredText, use a role or directive if one is available.
Don't apply emphasis to text in titles and headings. An exception would be if a title of a page or a heading of a section covers some code or command.
Don't change the case of the text to emphasize a term. This includes showing a general term in all capitals, small capitals, or initial capitals. If you are representing all-cap text from the user interface, write it as initial cap instead.
Don't use color to distinguish text.
Use quotation marks only as directed in this topic and in Quotation marks.
The following table shows the text formatting to use for different text elements. The following style differences are highlighted:
Content that documents a CLI or API versus a GUI
- Application names
Apply no additional formatting.
Code Example
You must configure MongoDB Compass. Rendered Example
You must configure MongoDB Compass.
- Area (group box) names
Format using
:guilabel:
role and capitalize the first letter of each word.Code Example
In the :guilabel:`Edit Signature` area, enter the text that you want to appear in your signature. Rendered Example
In the Edit Signature area, enter the text that you want to appear in your signature.
- Argument names
Format using
monospace
text.Code Example
To list or retrieve files from a node that's running the OpenCenter agent, use the ``file`` argument with the ``opencentercli`` node command. Rendered Example
To list or retrieve files from a node that's running the OpenCenter agent, use the
file
argument with theopencentercli
node command.- Attribute names
Format using
monospace
text.Code Example
The ``expires`` attribute denotes the time after which the token automatically becomes invalid. Rendered Example
The
expires
attribute denotes the time after which the token automatically becomes invalid.- Box names
This covers check box, combo box, group box, list box, spin box, and text box. Format them using the
:guilabel:
role.Code Example
Select the :guilabel:`Manually configure server settings or additional server types` check box. Retype the password that you entered in the :guilabel:`Password` box. Rendered Example
Select the Manually configure server settings or additional server types check box.
Retype the password that you entered in the Password box.
- Button names
This covers command, option, radio. Format using the
:guilabel:
role.Code Example
Select :guilabel:`Microsoft Exchange` and then click :guilabel:`Next`. Rendered Example
Select Microsoft Exchange and then click Next.
- Cascades
Order by menu, then field.
Format using the
:guilabel:
role.Separate levels with >.
Code Example
Select :guilabel:`Start > Control Panel`, and then click the :guilabel:`Mail` icon. Rendered Example
Select Start > Control Panel, and then click the Mail icon.
- Check box names
Format using
:guilabel:
role.Code Example
Select the :guilabel:`Manually configure server settings or additional server types` check box. Rendered Example
Select the Manually configure server settings or additional server types check box.
- Code, Inline
Format using
monospace
text.Code Example
``grep "ftp" /etc/xinetd.d/*`` Rendered Example
grep "ftp" /etc/xinetd.d/*
- Column names
Format using
:guilabel:
role.Code Example
Sort the backups by server by clicking the :guilabel:`Server` column label. Rendered Example
Sort the backups by server by clicking the Server column label.
- Combo box names
Format using
:guilabel:
role.Code Example
Select a name from the :guilabel:`Send to` list, or type a new name. Rendered Example
Select a name from the Send to list, or type a new name.
- Command names
Format using
monospace
text.Code Example
Check the architecture on Linux by using the ``uname -a`` command. Rendered Example
Check the architecture on Linux by using the
uname -a
command.- Command syntax
Varies by operating system:
Linux, macOS
Format using the
.. code-block:: console
directive.DOS, Windows Command-Line Interpreter
Format using the
.. code-block:: doscon
directive.Windows Powershell
Format using the
.. code-block:: ps1con
directive.Omit the command prompt if you aren't displaying the response in the same code block.
Code Example
If a service isn't running, use the service command to start it, as follows: .. code-block:: console :copyable: false sudo service httpd start To set your home directory path: .. code-block:: doscon :copyable: false SET HOME=<home-directory> To retrieve your home directory path: .. code-block:: ps1con :copyable: false echo $env:HOMEPATH Rendered Example
If a service isn't running, use the service command to start it, as follows:
sudo service httpd start To set your home directory path:
SET HOME=<home-directory> To retrieve your home directory path:
echo $env:HOMEPATH - Configuration File, INI style
Format using the
.. code-block:: ini
directive.Code Example
.. code-block:: ini :copyable: false mmsBaseUrl=http://example.com:8080 Rendered Example
mmsBaseUrl=http://example.com:8080 - Configuration File, YAML style
Format using the
.. code-block:: yaml
directive.Code Example
.. code-block:: yaml :copyable: false --- apiVersion: mongodb.com/v1 kind: MongoDB metadata: name: <myShardedCluster> spec: shardCount: 2 mongodsPerShardCount: 3 mongosCount: 2 configServerCount: 3 version: 4.2.2-ent opsManager: configMapRef: name: <configMap.metadata.name> # Must match metadata.name in ConfigMap file credentials: <myCredentials> type: ShardedCluster persistent: true Rendered Example
apiVersion: mongodb.com/v1 kind: MongoDB metadata: name: <myShardedCluster> spec: shardCount: 2 mongodsPerShardCount: 3 mongosCount: 2 configServerCount: 3 version: 4.2.2-ent opsManager: configMapRef: name: <configMap.metadata.name> # Must match metadata.name in ConfigMap file credentials: <myCredentials> type: ShardedCluster persistent: true - Cross-references
- Database names
Format using
monospace
text.Code Example
Start by creating a new database called ``mytestdb``. Rendered Example
Start by creating a new database called
mytestdb
.- Dialog box names
Format using the
:guilabel:
role.Code Example
In the :guilabel:`Microsoft Exchange` dialog box, click :guilabel:`Apply` and then click :guilabel:`OK`. Rendered Example
In the Microsoft Exchange dialog box, click Apply and then click OK.
- Directory names
Format using
monospace
text.Code Example
The following example shows a basic configuration for the FTP service, in a file in the ``/etc/xinetd.d/`` directory. Rendered Example
The following example shows a basic configuration for the FTP service, in a file in the
/etc/xinetd.d/
directory.- Document titles
Format using italics.
Note
You can't use italic if the title is a hyperlink.
Code Example
For details about code examples, see the "Code examples" section in the *Microsoft Style for Technical Publications, 4th Edition*. Rendered Example
For details about code examples, see the "Code examples" section in the Microsoft Style for Technical Publications, 4th Edition.
- Element names
Format using
monospace
text.Code Example
The ``message`` element returns a human-readable message that's appropriate for display to the end user. Rendered Example
The
message
element returns a human-readable message that's appropriate for display to the end user.- Email addresses, not clickable
Format using boldface.
Code Example
**your.name@example.com** Rendered Example
your.name@example.com
- Email addresses, clickable
Apply no additional formatting.
Code Example
If you have any questions regarding this agreement or the backup software, please direct all correspondence to: legal@mongodb.com. Rendered Example
if you have any questions regarding this agreement or the backup software, please direct all correspondence to: legal@mongodb.com.
- Emphasis
Format using italics.
Code Example
Offset *must* be a multiple of the limit (or zero); otherwise, a Bad Request exception is generated. Rendered Example
Offset must be a multiple of the limit (or zero); otherwise, a Bad Request exception is generated.
- Environment variables
Varies by operating system:
Linux, macOS
Format using
monospace
text and uppercase letters. Start with$
when getting, omit the$
when assigning.HOME=<home-directory> echo $HOME DOS, Windows Command-Line Interpreter
Format using
monospace
text and uppercase letters. Start and end with%
when getting, omit the%
when assigning.SET HOME=<home-directory> echo %HOME% Windows Powershell
Format using
monospace
text and uppercase letters. Start with$
when getting and assigning.$env:HOMEPATH='<home-directory>' echo $env:HOMEPATH Code Example
Copy the binaries into a directory listed in your ``PATH`` variable, such as ``/usr/local/bin`` (Update ``/path/to/the/mongodb-directory/`` with your installation directory as appropriate.) Rendered Example
Copy the binaries into a directory listed in your
PATH
variable, such as/usr/local/bin
(Update/path/to/the/mongodb-directory/
with your installation directory as appropriate.)- Environment variables
Format using
monospace
text.Code Example
Export the tenant ID to the ``$account`` environment variable and the authentication token to the ``$token`` environment variable. Rendered Example
Export the tenant ID to the
$account
environment variable and the authentication token to the$token
environment variable.- Error messages
Format using
monospace
text inline. If the format of the error aids in user understanding, use the appropriate.. code-block::
directive.Code Example
If your comment to an acknowledgement is too long, the API returns: ``Acknowledgement comment too long. It must not exceed <number> characters.`` Rendered Example
If your comment to an acknowledgement is too long, the API returns:
Acknowledgement comment too long. It must not exceed <number> characters.
- Examples, code
Format using the
.. code-block::
directive with corresponding. Pygment lexerCode Example
.. code-block:: javascript :copyable: false db.collection.create_index( [ (<keyAndIndexTypeSpecification> ], <options> ) .. code-block:: java :copyable: false collection.createIndex( <keyAndIndexTypeSpecification>, <options> ) Rendered Example
db.collection.create_index( [ (<keyAndIndexTypeSpecification>) ], <options> ) collection.createIndex( <keyAndIndexTypeSpecification>, <options> ) - Field names, GUI
Format using
:guilabel:
role.Code Example
In the :guilabel:`Database Name` field, enter a database name identifier. Rendered Example
In the Database Name field, enter a database name identifier.
- File names and extensions
Format using
monospace
text.Code Example
To remove the ``vs_quantum-api.cfg`` file from the ``haproxy.d`` directory and retain it, you can move it to another directory. Rendered Example
To remove the
vs_quantum-api.cfg
file from thehaproxy.d
directory and retain it, you can move it to another directory.- Flags
Format using
monospace
text.Code Example
Use the ``-t`` flag to add a timestamp to the results. Rendered Example
Use the
-t
flag to add a timestamp to the results.- Folder names
Format using
monospace
text.Code Example
Container names are sorted based on a binary comparison, a single built-in collating sequence that compares string data using the ``memcmp()`` function, regardless of text encoding. Rendered Example
Container names are sorted based on a binary comparison, a single built-in collating sequence that compares string data using the
memcmp()
function, regardless of text encoding.- Glossary terms
Format using
:term:
role.Code Example
MongoDB deploys a :term:`replica set` after you click :guilabel:`Save`. Rendered Example
MongoDB deploys a replica set after you click Save.
- Group box names
Format using
:guilabel:
role.Code Example
In the :guilabel:`Edit Signature` area, enter the text that you want to appear in your signature. Rendered Example
In the Edit Signature area, enter the text that you want to appear in your signature.
- GUI labels
Format using
:guilabel:
role.Note
Exception: Show window, dialog box, wizard, page, panel, and screen names in regular text unless they need to be distinguished from the surrounding text. In such cases, use bold.
Code Example
In the :guilabel:`Microsoft Exchange` dialog box, click :guilabel:`Apply` and then click :guilabel:`OK`. On the :guilabel:`Choose Service` page, select :guilabel:`Microsoft Exchange or compatible service`, and then click :guilabel:`Next`. Rendered Example
In the Microsoft Exchange dialog box, click Apply and then click OK.
On the Choose Service page, select Microsoft Exchange or compatible service, and then click Next.
Read the preliminary steps in the Configure Your Server wizard, and then click Next.
- HTML tags
Format using
monospace
text.Code Example
Avoid putting the ``xml:id`` attribute on the ``title`` tag. Rendered Example
Avoid putting the
xml:id
attribute on thetitle
tag.- Hyperlinks, clickable
- Icon names
Format using
:guilabel:
role.Code Example
To verify which OS version you're running, click the :guilabel:`Apple` icon in the top-left corner and then select :guilabel:`About This Mac`. Rendered Example
To verify which OS version you're running, click the Apple icon in the top-left corner and then select About This Mac.
- Keyboard key combinations, names, and shortcuts
Format using the
:kbd:
role.Code Example
Press :kbd:`Shift-G` and then press :kbd:`Enter`. Rendered Example
Press
Shift-G
and then pressEnter
.- Letters as letters
Format using italics.
Code Example
Place *i* before *e* except after *c*. Rendered Example
Place i before e except after c.
- Links, clickable
- List box names and selections
Format using
:guilabel:
role.Code Example
From the :guilabel:`Account Type` list, select :guilabel:`Exchange 2007`. To view these settings, select :guilabel:`Configure Backup` from the :guilabel:`Backup Actions` list. Rendered Example
From the Account Type list, select Exchange 2007.
To view these settings, select Configure Backup from the Backup Actions list.
- Menu names and commands
Format using
:guilabel:
role.Code Example
Right-click the volume and select :guilabel:`Take Offline`. From the :guilabel:`Outlook` menu, select :guilabel:`Preferences`. Rendered Example
Right-click the volume and select Take Offline.
From the Outlook menu, select Preferences.
- Menu sequences
- Format as Cascades.
- Messages (error, warning)
Format using
monospace
text.Code Example
In SQL Server Management Studio, when you right-click a SQL Server 2012 database and selecting :guilabel:`Properties`, the following error message appears: ``The user doesn't have permission to perform this action.`` Rendered Example
In SQL Server Management Studio, when you right-click a SQL Server 2012 database and selecting Properties, the following error message appears:
The user doesn't have permission to perform this action.
- Method names, HTTP
Format using
monospace
with all capital letters.Code Example
Client authentication is provided through a REST interface by using the ``GET`` method. Rendered Example
Client authentication is provided through a REST interface by using the
GET
method.- Option names, command
Format using
:option:
role.Code Example
The size of the oplog is only configurable during the first run using the ``--oplogSize`` argument to the :binary:`~bin.mongod` command, or preferably, the :setting:`~replication.oplogSizeMB` setting in the MongoDB configuration file. If you do not specify this on the command line before running with the :option:`mongod --replSet` option, :binary:`~bin.mongod` creates a default sized oplog. Rendered Example
The size of the oplog is only configurable during the first run using the
--oplogSize
argument to themongod
command, or preferably, theoplogSizeMB
setting in the MongoDB configuration file. If you do not specify this on the command line before running with the--replSet
option,mongod
creates a default sized oplog.- Option button names
Format using
:guilabel:
role.Code Example
Select :guilabel:`Microsoft Exchange` and then click :guilabel:`Next`. Rendered Example
Select Microsoft Exchange and then click Next.
- Package names
Format using
monospace
text.Code Example
You must install the ``libvirt`` package. Rendered Example
You must install the
libvirt
package.- Page names
Format using
:guilabel:
role.Code Example
On the :guilabel:`Preferences` page, you determine how frequently you receive email about all the activity on your account: daily, weekly, or both. On the :guilabel:`Server Settings` page, click :guilabel:`Check Name`, type your password, and then click :guilabel:`OK`. Rendered Example
On the Preferences page, you determine how frequently you receive email about all the activity on your account: daily, weekly, or both.
On the Server Settings page, click Check Name, type your password, and then click OK.
- Panes, named and unnamed
Format using
:guilabel:
role.Code Example
To verify that your TLS binding works, select your website in the :guilabel:`Connections` pane (if it's not already selected) and then click :guilabel:`Browse ipAddress (https)` in the :guilabel:`Actions` pane. In the navigation pane, select :guilabel:`Compose Email`. Rendered Example
To verify that your TLS binding works, select your website in the Connections pane (if it's not already selected) and then click Browse ipAddress (https) in the Actions pane.
In the navigation pane, select Compose Email.
- Paths
Format using
monospace
text.Code Example
The path to Perl is ``#!/usr/bin/perl -w``. In the URI path ``https://cloud.mongodb.com/api/public/v1.0``, the API version is 1. Rendered Example
The path to Perl is
#!/usr/bin/perl -w
.In the URI path
https://cloud.mongodb.com/api/public/v1.0
, the API version is 1.- Permissions
Apply no additional formatting. Covers file permissions on any operating system.
Code Example
Log in to a shell as the user who has write permissions to ``/usr/local/bin`` on your local computer. Rendered Example
Log in to a shell as the user who has write permissions to
/usr/local/bin
on your local computer.- Placeholder text
- Privileges
Apply no additional formatting unless the privilege is an operating system command like
sudo
. Otherwise, you can say elevated privileges.Code Example
The following examples assume that you're making the firewall changes as a normal user with ``sudo`` privileges. The user is granted ALL privileges on the database. Rendered Example
The following examples assume that you're making the firewall changes as a normal user with
sudo
privileges.The user is granted ALL privileges on the database.
- Qualifiers
Format using italic.
Code Example
1. *(Optional)* Enter a new name for the image. You can tell that the Managed Cloud post-build automation has successfully completed as follows: *(Windows servers)* The following file is created: **C:\\windows\\temp\\rs\_managed\_cloud\_automation\_complete.txt** *(Linux servers)* The following file is created: **/tmp/rs\_managed\_cloud\_automation\_complete** Rendered Example
(Optional) Enter a new name for the image.
You can tell that the Managed Cloud post-build automation has successfully completed as follows:
(Windows servers) The following file is created: C:\windows\temp\rs_managed_cloud_automation_complete.txt
(Linux servers) The following file is created: /tmp/rs_managed_cloud_automation_complete
- Quotations from another source
Format using Quotation marks, or block quote formatting
Code Example
"Scalability is key for our business," explained Nathan Goff, Inavero Operations Director and Partner. "There's nothing worse than making our clients look bad to their customers." Rendered Example
"Scalability is key for our business," explained Nathan Goff, Inavero Operations Director and Partner. "There's nothing worse than making our clients look bad to their customers."
- Radio button names
Format using
:guilabel:
role.Code Example
Select :guilabel:`Microsoft Exchange` and then click :guilabel:`Next`. Rendered Example
Select Microsoft Exchange and then click Next.
- Role names
Format using the
:authrole:
or:atlasrole:
as appropriate for the documented product's roles. Otherwise, format as regular text.Code Example
The :authrole:`Global Owner` role has the permissions to create, read, update, and delete resources within multiple designated products where access is granted. Rendered Example
The
Global Owner
role has the permissions to create, read, update, and delete resources within multiple designated products where access is granted.- Sequences
- Format as Cascades.
- Shell, Terminal, or Command Prompt
- Format as Command syntax.
- Syntax statements
Format using
monospace
text.Code Example
The main command used to change a file’s owner or group is ``chown``. The most common syntax used with ``chown`` is as follows: ``chown user:group file1 file2 file3`` Rendered Example
The main command used to change a file’s owner or group is
chown
. The most common syntax used withchown
is as follows:chown user:group file1 file2 file3
- Tab names
Format using
:guilabel:
role.Code Example
In the :guilabel:`Microsoft Exchange` dialog box, click the :guilabel:`Connection` tab and then select the :guilabel:`Connect to Microsoft Exchange using HTTP` check box. Rendered Example
In the Microsoft Exchange dialog box, click the Connection tab and then select the Connect to Microsoft Exchange using HTTP check box.
- Terms, new
Format using italics.
Code Example
MongoDB instances that are built using the base Linux images are created without a dedicated swap partition and with *swappiness* (a measure of how the Linux kernel tries to use swap memory) set to 0. Rendered Example
MongoDB instances that are built using the base Linux images are created without a dedicated swap partition and with swappiness (a measure of how the Linux kernel tries to use swap memory) set to 0.
- Terms, unique sense
Don't use.
- UI label
Format using
:guilabel:
role. If the UI uses all capital letters, change to capitalizing the first letter of each word.Code Example
In the :guilabel:`Microsoft Exchange` dialog box, click :guilabel:`Apply` and then click :guilabel:`OK`. On the :guilabel:`Choose Service` page, select :guilabel:`Microsoft Exchange or compatible service`, and then click :guilabel:`Next`. Read the preliminary steps in the :guilabel:`Configure Your Server` wizard, and then click :guilabel:`Next`. Rendered Example
In the Microsoft Exchange dialog box, click Apply and then click OK.
On the Choose Service page, select Microsoft Exchange or compatible service, and then click Next.
Read the preliminary steps in the Configure Your Server wizard, and then click Next.
- URL, not clickable
Format using boldface.
Code Example
To access the web interface, open your web browser and navigate to **http://yourDomain.com/zipit-install.php**. Rendered Example
To access the web interface, open your web browser and navigate to http://yourDomain.com/zipit-install.php.
- URL, clickable
- User GUI input
Format using boldface.
Code Example
In the :guilabel:`Server` text box, type **outlook**. Rendered Example
In the Server text box, type outlook.
- User CLI input
Format inline text that the user types into an IDE, editor, or prompt using
monospace
text. Recommend using a.. code-block::
instead.Code Example
Create a file by using a text editor. Insert the following code: ``<?php phpinfo(); ?>`` For the username, enter ``admin``. Rendered Example
Create a file by using a text editor, and insert the following code:
<?php phpinfo(); ?>
For the username, enter
admin
.- Variable text
- Window names
Format using the
:guilabel:
role.Code Example
In the :guilabel:`Network Connections` window, right-click the private adapter and select :guilabel:`Properties`. Rendered Example
In the Network Connections window, right-click the private adapter and select Properties.
- Wizard names, wizard page names
Format using the
:guilabel:
role.Code Example
On the :guilabel:`Welcome` page of the :guilabel:`Active Directory Domain Services Installation` Wizard, clear the :guilabel:`Use advanced mode installation` check box, and then click :guilabel:`Next`. Rendered Example
On the Welcome page of the Active Directory Domain Services Installation Wizard, clear the Use advanced mode installation check box, and then click Next.
- Words as words
Format using italics.
Code Example
Don't use *button* and *icon* interchangeably. If you're referring to a command button or toolbar button (labeled or unlabeled), use *button*. If you're referring to a graphic on a screen, window, or other area, use *icon*. Rendered Example
Don't use button and icon interchangeably. If you're referring to a command button or toolbar button (labeled or unlabeled), use button. If you're referring to a graphic on a screen, window, or other area, use icon.