Clarify shorthand (#843)

Author: MetRonnie

src/reference/config/shorthand.rst

@@ -1,12 +1,14 @@
-We often use a compact single-line notation to refer to nested config items:
+In the documentation, we often use a compact single-line notation to refer to
+nested config items, where we drop the additional brackets at each level:
 
 ``[section]``
    An entire section.
 ``[section]setting``
    A setting within a section.
 ``[section]setting=value``
    The value of a setting within a section.
-``[section][sub-section]another-setting``
+``[section][sub section]another setting``
    A setting within a sub-section.
 
-In the file, however, section headings need additional brackets at each level.
+This is purely for making it easier to refer to items; they cannot be written
+this way in the ``flow.cylc`` file.

src/tutorial/scheduling/graphing.rst

@@ -55,10 +55,10 @@ Example
                String
            """
 
-Shorthand
-^^^^^^^^^
+.. admonition:: Shorthand
+   :class: tip
 
-.. include:: ../../reference/config/shorthand.rst
+   .. include:: ../../reference/config/shorthand.rst
 
 Duplicate Items
 ^^^^^^^^^^^^^^^