From cabbdef4d795e455ab0ec2f8b27be52335932f68 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Mon, 19 Jul 2021 16:12:01 +0100
Subject: [PATCH 1/3] Added More details of the working of rose stem to docs

---
 cylc/rose/__init__.py | 47 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 5 deletions(-)

diff --git a/cylc/rose/__init__.py b/cylc/rose/__init__.py
index bd3ee7de..ead3fc86 100644
--- a/cylc/rose/__init__.py
+++ b/cylc/rose/__init__.py
@@ -19,9 +19,24 @@
 
 Cylc Rose is the bridge between Rose suite configurations and Cylc workflows.
 
-Cylc Rose is a replacement for the ``rose suite-run`` command (present in Rose
-versions 2019.01 and earlier). It reads the ``rose-suite.conf`` file and
-performs the required actions.
+Cylc Rose allows ``cylc install`` to replace the ``rose suite-run``
+command (present in Rose versions 2019.01 and earlier). It reads the
+``rose-suite.conf`` file and:
+
+- Makes environment and template variables available
+  to Cylc.
+- Installs files.
+- Records information in about the configuration installed in
+  ``~/cylc-run/<workflow>/opt/rose-suite-cylc-install.conf``
+
+
+The following Cylc commands will read Rose Suite Configurations:
+
+- ``cylc validate``
+- ``cylc graph``
+- ``cylc list``
+- ``cylc config``
+
 
 Rose Config
 -----------
@@ -113,12 +128,34 @@
    +       [[Hello_Mars]]
 
 
+.. _rose-stem:
+
 Rose Stem
 =========
 
+.. seealso::
+
+   `Rose Stem documentation
+   <https://metomi.github.io/rose/2019.01.2/html/tutorial/rose/furthertopics/
+   rose-stem.html>`_
+
+
 Cylc Rose provides a Rose Stem command, if FCM is installed on your system.
-See `the Rose Stem documentation
-<https://metomi.github.io/rose/2019.01.2/html/tutorial/rose/furthertopics/rose-stem.html>`_
+At Cylc 8 Rose Stem is a wrapper to ``cylc install`` rather than
+``rose suite-run``.
+
+Rose Stem is a wrapper around the ``cylc install`` command which
+provides some additional jinja2 variables.
+
+Cylc 8 stores variables set by rose and rose-stem in the optional
+configuration file ``~/cylc-run/my_workflow/opt/rose-suite-cylc-install.conf``.
+
+.. caution::
+
+   To reinstall a rose stem suite use ``cylc reinstall``.  Cylc can get any
+   options you do not change from the ``rose-suite-cylc-install.conf``` file.
+   Using ``rose stem`` a second time will attempt install a new copy
+   of your rose stem suite.
 
 """
 

From 220985214241a15271f27f19614dc10347831f92 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Tue, 20 Jul 2021 14:20:09 +0100
Subject: [PATCH 2/3] added a note about rose-suites and cylc-workflows

---
 cylc/rose/__init__.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/cylc/rose/__init__.py b/cylc/rose/__init__.py
index ead3fc86..e3ec0bdd 100644
--- a/cylc/rose/__init__.py
+++ b/cylc/rose/__init__.py
@@ -41,6 +41,11 @@
 Rose Config
 -----------
 
+.. attention::
+
+   Rose configurations for Cylc **workflows** continue to be referred to
+   as Rose **suites**.
+
 A fuller description of
 :ref:`rose suite config is available here<Rose Suites>`.
 

From 2ac02094e53640bb64a32a6bc8613ceb5cae2df7 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Wed, 21 Jul 2021 15:19:16 +0100
Subject: [PATCH 3/3] Update cylc/rose/__init__.py

Co-authored-by: Melanie Hall <37735232+datamel@users.noreply.github.com>
---
 cylc/rose/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cylc/rose/__init__.py b/cylc/rose/__init__.py
index e3ec0bdd..0f8cb6e1 100644
--- a/cylc/rose/__init__.py
+++ b/cylc/rose/__init__.py
@@ -150,7 +150,7 @@
 ``rose suite-run``.
 
 Rose Stem is a wrapper around the ``cylc install`` command which
-provides some additional jinja2 variables.
+provides some additional Jinja2 variables.
 
 Cylc 8 stores variables set by rose and rose-stem in the optional
 configuration file ``~/cylc-run/my_workflow/opt/rose-suite-cylc-install.conf``.