user guide: move "compound commands" in with "installing workflows"

Author: oliver-sanders

src/7-to-8/major-changes/cli.rst

@@ -113,12 +113,17 @@ GUI. Consequently the following commands have also been removed:
 The ``cylc gui`` command remains, it launches a standalone version of the
 web GUI (providing the `Cylc UI Server`_ is installed).
 
-.. seealso::
-
-   :ref:`CompoundCommands` - For your convenience we have
-    provided commands which represent common working practices. For
-    example ``cylc vip`` (Validate-Install-Play) which runs
-    ``cylc validate``, ``cylc install`` and ``cylc play``.
+Additionally, there are two
+":ref:`compound commands <installing_workflows.compound_commands>`"
+which automate common working practices, namely:
+
+``cylc vip``
+   Validate, install and play a workflow. This is similar to what
+   ``rose suite-run`` did.
+``cylc vr``
+   Valiate, install, then either reload (if the workflow is running) or restart
+   (if it is stopped) the workflow. This is similar to what
+   ``rose suite-run --reload`` and ``rose suite-run --restart`` did.
 
 
 Cylc 8 Standardised IDs

src/user-guide/compound-commands.rst

@@ -25,6 +25,11 @@ location, called a :term:`source directory`.
 ``cylc install`` will create a new run directory in the :term:`cylc-run directory`
 for each installation of a workflow.
 
+.. contents:: Contents
+   :depth: 2
+   :local:
+
+
 .. _Install-Workflow:
 
 The Cylc Install Command
@@ -449,3 +454,51 @@ There are some occasions when installation is expected to fail:
   previous installation. i.e. running ``cylc install`` in
   ``~/cylc-src/my-flow``, followed by running ``cylc install`` from
   ``~/different/my-flow``.
+
+
+.. _installing_workflows.compound_commands:
+
+Compound Commands
+-----------------
+
+Cylc provides compound commands which carry out multiple operations.
+
+For example Cylc provides a command to validate, install and play a workflow.
+
+Compound commands make common ways of working easier.
+
+.. note::
+
+   Use ``cylc command --help`` to get help for each compound command,
+   including a full list of available options.
+
+
+``cylc vip`` (Validate, Install and Play)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``cylc vip /home/me/cylc-src/my-workflow`` is the same as running:
+
+.. code-block:: bash
+
+   $ cylc validate /home/me/cylc-src/my-workflow
+   $ cylc install /home/me/cylc-src/my-workflow
+   INSTALLED my-workflow/run1 from /home/me/cylc-src/my-workflow
+   $ cylc play my-workflow
+
+``cylc vr`` (Validate, Reinstall and Reload or Play)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``cylc vr my-workflow`` is the same as running:
+
+.. code-block:: bash
+
+   # Check that the changes you want to
+   # make will be valid after installation:
+   $ cylc validate my-workflow --against-source
+   $ cylc reinstall my-workflow
+
+   # If workflow is running:
+   $ cylc reload my-workflow
+
+   # If workflow is stopped:
+   $ cylc play my-workflow