Sphinx supports a large number of inline markup elements called roles. The Clear Linux* OS documentation encourages the use of as many roles as possible. Thus, you can use any additional roles supported by Sphinx not listed here. Please refer to the Sphinx reStructuredText Markup documentation for the full list of supported roles.

The following markup is required in every instance unless otherwise specified. Each item provides a syntax example followed by the rendered result.

Abbreviations

Use the :abbr: abbreviation role to define an acronym or an initialism. Add the abbreviation markup only once per file. After the abbreviation, the acronym can be used without further definition or markup. Do not use abbreviation markup on headings.

:abbr:`API (Application Program Interface)`
API
OS Commands

Use the :command: role when the name of a specific command is used in a paragraph for emphasis. Use the .. code-block:: directive for fully actionable commands in a series of steps.

:command:`make`
make
Commandline Options

In most cases, use asterisks “*” to emphasize the name of a command option.

Use the *-p* option to print the file.
Use the -p option to print the file.

However, if you have defined an .. option:: directive, you may use the :option: role. Note that the result links back to the option definition.

.. option: -o <output.xsl>

   Description of the -o option

The :command:`pandoc` command can be used without :option:`-o`
-o <output.xsl>

Description of the -o option

The pandoc command can be used without -o
Files

Use the :file: role to emphasize a filename or directory. Do not use the role inside a code-block but use it inside all notices that contain files or directories. Place variable parts of the path or filename in brackets {}.

:file:`collaboration.rst`

:file:`doc/{user}/collaboration/figures`
collaboration.rst

doc/user/collaboration/figures
GUI Objects

Use the :guilabel: role to emphasize elements of a graphic user interface within a description. It replaces the use of quotes when referring to windows’ names, button labels, options, or single menu elements. Always follow the marked element with the appropriate noun. For example:

In the :guilabel:`Tools` menu, click :guilabel:`settings`.
In the Tools menu, click settings.
Menu Navigation

Use the :menuselection: role to indicate the navigation through a menu ending with a selection. Every :menuselection: element can have up to two menu steps before the selected item. If more than two steps are required, it can be combined with a :guilabel: or with another :menuselection: element. For example:

Go to :guilabel:`File` and select :menuselection:`Import --> Data Base --> MySQL`.

Go to :menuselection:`Window --> View` and select :menuselection:`Perspective --> Other --> C++`
Go to File and select Import ‣ Data Base ‣ MySQL.

Go to Window ‣ View and select Perspective ‣ Other ‣ C++
Makefile Variables

Use the :makevar: role to emphasize the name of a Makefile variable. The role can include only the name of the variable or the variable plus its value.

:makevar:`PLATFORM_CONFIG`

:makevar:`PLATFORM_CONFIG=basic_atom`
PLATFORM_CONFIG

PLATFORM_CONFIG=basic_atom
Environment Variables

Use the :envvar: role to emphasize the name of environment variables. Just as with :makevar:, the markup can include only the name of the variable or the variable plus its value.

:envvar:`ZEPHYR_BASE`

:envvar:`QEMU_BIN_PATH=/usr/local/bin`
ZEPHYR_BASE

QEMU_BIN_PATH=/usr/local/bin