major edits to inline.rst including use of parsed-literal for rendered examples

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 <output.xsl>
+     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 <output.xsl>
 
-         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 <output.xsl>
+
+     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