Improve nested config shorthand docs.

Author: hjoliver

src/7-to-8/summary.rst

@@ -46,6 +46,11 @@ take action on any warnings.
 .. TODO Add ref to breaking changes section within Major changes, once created,
    including optional ouputs.
 
+.. note::
+
+   Validation warnings use a :ref:`shorthand notation<config_item_shorthand>`
+   to refer to nested configuration settings on a single line, like this:
+   ``[section][sub-section]item``.
 
 
 New Web and Terminal UIs

src/reference/config/file-format.rst

@@ -158,23 +158,19 @@ Include-files
    :ref:`Jinja2's <Jinja>` template inclusion mechanism can be used with Cylc
    too.
 
+.. _config_item_shorthand:
 
 Shorthand
 ---------
 
-Throughout the documentation we refer to configuration settings in the
-following way:
-
-``[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``
-   A setting within a sub-section.
-
-.. warning::
-   We only use one set of square brackets at each level when writing nested
-   sections on one line like this. But in the file, each sub-section
-   gets additional square brackets as shown above.
+.. include:: shorthand.rst
+
+.. code-block:: cylc
+
+   # This:
+   #   [runtime][task-a][environment]FOO = foo
+   # Means:
+   [runtime]
+       [[task-a]]
+           [[[environment]]]
+               FOO = foo

src/reference/config/shorthand.rst

@@ -0,0 +1,12 @@
+We often use a compact single-line notation to refer to nested config items:
+
+``[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``
+   A setting within a sub-section.
+
+In the file, however, section headings need additional brackets at each level.

src/tutorial/scheduling/graphing.rst

@@ -58,18 +58,7 @@ Example
 Shorthand
 ^^^^^^^^^
 
-Throughout this tutorial we will refer to configuration settings in the following ways:
-
-``[section]``
-   An entire section.
-``[section]key``
-   A specific config item, within a section.
-``[section]key=value``
-   The value of a specific config item, within a section.
-``[section][sub-section]another-key``
-   Note we only use one set of square brackets per section heading when
-   writing on one line like this. In the config file each nested level
-   gets another set of square brackets.
+.. include:: ../../reference/config/shorthand.rst
 
 Duplicate Items
 ^^^^^^^^^^^^^^^