From e62a787d0fdd51bbc5b4b88d6a6d154b89e9ded0 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Fri, 31 May 2024 11:47:17 +0100
Subject: [PATCH] Suggest users prefer CYLC_SHARE_CYCLE_DIR to ROSE_DATAC

---
 .../furthertopics/date-time-manipulation.rst  | 36 ++++++++++++-------
 1 file changed, 23 insertions(+), 13 deletions(-)

diff --git a/sphinx/tutorial/rose/furthertopics/date-time-manipulation.rst b/sphinx/tutorial/rose/furthertopics/date-time-manipulation.rst
index 24783d35b..d727e5f43 100644
--- a/sphinx/tutorial/rose/furthertopics/date-time-manipulation.rst
+++ b/sphinx/tutorial/rose/furthertopics/date-time-manipulation.rst
@@ -11,9 +11,9 @@ present cycle using::
    cylc cyclepoint --offset-hours=-3
 
 The `isodatetime`_ command provides functionality
-beyond ``cylc cyclepoint``. Rose also provides the :envvar:`ROSE_DATAC` environment
-variable which provides an easy way to get the path of the ``share/cycle``
-directory.
+beyond ``cylc cyclepoint``. Cylc also provides the ``CYLC_SHARE_CYCLE_DIR``
+environment variable which provides an easy way to get the path of the
+``share/cycle/<point>`` directory.
 
 
 The ``isodatetime`` Command
@@ -72,6 +72,11 @@ which allows you to use the special ``ref`` argument:
 The ``ROSE_DATAC`` Environment Variable
 ---------------------------------------
 
+.. note::
+
+   From Cylc 8.3.1 the variable ``CYLC_SHARE_CYCLE_DIR`` should be preferred
+   to ``ROSE_DATAC``.
+
 There are two locations where task output is likely to be located:
 
 The work directory
@@ -96,22 +101,27 @@ The share directory
       <run directory>/share/cycle/<cycle>
 
    These are called the ``share/cycle`` directories.
-
-   The path to the root of the share directory is provided by the
-   ``CYLC_WORKFLOW_SHARE_DIR`` environment variable so the path to the cycle
-   subdirectory would be::
+   ``CYLC_SHARE_CYCLE_DIR`` provides the path to::
 
       "$CYLC_WORKFLOW_SHARE_DIR/cycle/$CYLC_TASK_CYCLE_POINT"
 
-The :ref:`command-rose-task-env` command provides the environment variable
-:envvar:`ROSE_DATAC` which is a more convenient way to obtain the path of the
-``share/cycle`` directory.
 
 To get the path to a previous (or a future) ``share/cycle`` directory we can
-provide an offset to :ref:`command-rose-task-env` e.g::
+provide an offset to isodatetime:
+
+.. code-block:: bash
+
+   isodatetime "${CYLC_TASK_CYCLE_POINT} --offset -P1D
+
+Which can be used to provide custom offset directory locations:
+
+.. code-block:: bash
 
-   rose task-env --cycle-offset=PT1H
+   # Cylc task script
+   CYCLE_POINT_MINUS_P1D=$(isodatetime "${CYLC_TASK_CYCLE_POINT} --offset -P1D)"
+   SHARE_CYCLE_DIR_MINUS_P1D="${CYLC_WORKFLOW_SHARE_DIR}/cycle/${CYCLE_POINT_MINUS_P1D}"
+   mkdir -p "${SHARE_CYCLE_DIR_MINUS_P1D}"
+   echo "I believe in ..." > "${SHARE_CYCLE_DIR_MINUS_P1D}/somefile"
 
-The path is then made available as the ``ROSE_DATACPT1H`` environment variable.
 
 .. TODO - Write a short practical using ROSE_DATAC and isodatetime.