diff --git a/source/clear-linux/reference/collaboration/documentation/inline.rst b/source/clear-linux/reference/collaboration/documentation/inline.rst index 9eb4d207..3efc0195 100644 --- a/source/clear-linux/reference/collaboration/documentation/inline.rst +++ b/source/clear-linux/reference/collaboration/documentation/inline.rst @@ -6,133 +6,157 @@ Inline Markup Sphinx supports a large number of inline markup elements called roles. The |CLOSIA| documentation encourages the use of as many roles as possible. Thus, you can use any additional roles supported by Sphinx -even if not listed here. Please refer to the `Sphinx Inline Markup`_ +not listed here. Please refer to the `Sphinx Inline Markup`_ documentation for the full list of supported roles. The following markup is required in every instance unless otherwise -specified. Each item provides examples and a template for the correct use of -the roles. +specified. Each item provides a syntax example followed by the rendered +result. -* Use the `:abbr:` abbreviation role to define an acronym or an initialism. +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)` - Template: + .. parsed-literal:: - ``:abbr:`TIA (This Is an Abbreviation)``` + :abbr:`API (Application Program Interface)` -* Use the `:command:` role when the name of a specific command is used in a +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` - Template: + .. parsed-literal:: - ``:command:`command``` + :command:`make` -* In most cases, use asterisks "*" to emphasize the name of a command - option. However, if you have defined an ``.. option::`` directive, you may - use the `:option:` role. For example: +Commandline Options + In most cases, use asterisks "*" to emphasize the name of a command + option. - Pandoc Options: + :: - .. option:: -f - .. option:: --all - .. option:: -o + Use the *-p* option to print the file. - The :command:`pandoc` command can be used without the :option:`-o` - option, creating an output file with the same name as the source - but a different extension. + .. parsed-literal:: + + 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. - Template: - .. code-block:: rest - .. option: option + .. option: -o - description of option + Description of the -o option - :option:`option` + The :command:`pandoc` command can be used without :option:`-o` -* Use the `:file:` role to emphasize a filename or directory. Do not use the + .. option:: -o + + Description of the -o option + + .. parsed-literal:: + + The :command:`pandoc` command can be used without :option:`-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 `{}`. + .. code-block:: rest + :file:`collaboration.rst` :file:`doc/{user}/collaboration/figures` - Template: + .. parsed-literal:: - .. code-block:: rest + :file:`collaboration.rst` - :file:`filename.ext` + :file:`doc/{user}/collaboration/figures` - :file:`path/or/directory` - -* Use the `:guilabel:` role to emphasize elements of a graphic +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. + :: - Press the :guilabel:`OK` button. + In the :guilabel:`Tools` menu, click :guilabel:`settings`. - In the :guilabel:`Settings` window you find - the :guilabel:`Hide Content` option. + .. parsed-literal:: - Template: + In the :guilabel:`Tools` menu, click :guilabel:`settings`. - ``:guilabel:`UI-Label``` - -* Use the `:menuselection:` role to indicate the navigation through a menu +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: - :menuselection:`File --> Save As --> PDF` + :: - Go to :guilabel:`File` and select :menuselection:`Import --> Data - Base --> MySQL`. + Go to :guilabel:`File` and select :menuselection:`Import --> Data Base --> MySQL`. + + Go to :menuselection:`Window --> View` and select :menuselection:`Perspective --> Other --> C++` + + .. parsed-literal:: + + Go to :guilabel:`File` and select :menuselection:`Import --> Data Base --> MySQL`. - Go to :menuselection:`Window --> View` and - select :menuselection:`Perspective --> Other --> C++` + Go to :menuselection:`Window --> View` and select :menuselection:`Perspective --> Other --> C++` - Template: - - ``:menuselection:`1stMenu --> 2ndMenu --> Selection``` - -* Use the `:makevar:` role to emphasize the name of a Makefile variable. +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` - Template: + .. parsed-literal:: - ``:makevar:`VARIABLE``` + :makevar:`PLATFORM_CONFIG` -* Use the `:envvar:` role to emphasize the name of environment + :makevar:`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` - Template: + .. parsed-literal:: - ``:envvar:`ENVIRONMENT_VARIABLE``` + :envvar:`ZEPHYR_BASE` + + :envvar:`QEMU_BIN_PATH=/usr/local/bin` .. _Sphinx Inline Markup: - http://sphinx-doc.org/markup/inline.html#inline-markup + http://sphinx-doc.org/markup/inline.html#inline-markup \ No newline at end of file