Improve Job Script Environment Variables reference

The variable CYLC_WORKFLOW_LOG_DIR was newly added, and existing
variables had their descriptions and examples improved, notably adding
the run sub-directory to the example paths. Variables have also been
slightly reordered to be more logically grouped.

The longer name for CYLC_TASK_LOG_ROOT does however make a scrollbar
appear, which may be undesirable.

Fixes: #779
Signed-off-by: James Frost <[email protected]>

Author: jfrost-mo

CONTRIBUTING.md

@@ -57,6 +57,7 @@ requests_).
  - Scott Wales
  - Elliot Fontaine
  - Mark Dawson
+ - James Frost
 <!-- end-shortlog -->
 
 (All contributors are identifiable with email addresses in the git version

src/reference/job-script-vars/var-list.txt

@@ -2,60 +2,63 @@ CYLC_VERSION                       # Version of cylc installation used
 CYLC_VERBOSE                       # Verbose mode, true or false
 CYLC_DEBUG                         # Debug mode (even more verbose), true or false
 
-CYLC_CYCLING_MODE                  # Cycling mode, e.g. gregorian
+CYLC_CYCLING_MODE                  # Cycling mode, e.g. "gregorian" or "integer"
 ISODATETIMECALENDAR                # Calendar mode for the `isodatetime` command,
                                    #   defined with the value of CYLC_CYCLING_MODE
                                    #   when in any datetime cycling mode
+CYLC_UTC                           # UTC mode, True or False
+TZ                                 # Set to "UTC" in UTC mode or not defined
 
-CYLC_WORKFLOW_FINAL_CYCLE_POINT    # Final cycle point
 CYLC_WORKFLOW_INITIAL_CYCLE_POINT  # Initial cycle point
+CYLC_WORKFLOW_FINAL_CYCLE_POINT    # Final cycle point
+
 CYLC_WORKFLOW_ID                   # Workflow ID
-                                   # e.g. "a/b/c/run1"
+                                   #   e.g. "foo/run1" or "a/b/c/run1"
 CYLC_WORKFLOW_NAME                 # Workflow ID with the run name removed
-                                   # (use CYLC_WORKFLOW_ID for most purposes)
-                                   # e.g. "a/b/c"
+                                   #   (use CYLC_WORKFLOW_ID for most purposes)
+                                   #   e.g. "foo" or "a/b/c"
 CYLC_WORKFLOW_NAME_BASE            # The basename of the workflow name
-                                   # (use CYLC_WORKFLOW_ID for most purposes)
-                                   # e.g. "c"
-CYLC_UTC                           # UTC mode, True or False
-TZ                                 # Set to "UTC" in UTC mode or not defined
+                                   #   (use CYLC_WORKFLOW_ID for most purposes)
+                                   #   e.g. "foo" or "c"
+CYLC_WORKFLOW_UUID                 # Workflow UUID string
 
-CYLC_WORKFLOW_RUN_DIR              # Location of the run directory in
-                                   # job host, e.g. ~/cylc-run/foo
 CYLC_WORKFLOW_HOST                 # Host running the workflow process
 CYLC_WORKFLOW_OWNER                # User ID running the workflow process
 
+CYLC_WORKFLOW_RUN_DIR              # Location of the run directory in job host,
+                                   #   e.g. ~/cylc-run/foo/run1
+CYLC_WORKFLOW_LOG_DIR              # Location of the scheduler's log files,
+                                   #   e.g. ~/cylc-run/foo/run1/log/scheduler
 CYLC_WORKFLOW_SHARE_DIR            # Workflow (or task!) shared directory
-CYLC_WORKFLOW_UUID                 # Workflow UUID string
-CYLC_WORKFLOW_WORK_DIR             # Workflow work directory
+                                   #   e.g. ~/cylc-run/foo/run1/share
+CYLC_WORKFLOW_WORK_DIR             # Workflow work directory,
+                                   #   e.g. ~/cylc-run/foo/run1/work
 
 CYLC_TASK_JOB                      # Job identifier expressed as
-                                   # CYCLE-POINT/TASK-NAME/SUBMIT-NUMBER
+                                   #   CYCLE-POINT/TASK-NAME/SUBMIT-NUMBER
                                    #   e.g. 20110511T1800Z/t1/01
-
+CYLC_TASK_ID                       # Task instance identifier CYCLE-POINT/TASK-NAME
+                                   #   e.g. 20110511T1800Z/t1
+CYLC_TASK_NAME                     # Job's task name, e.g. t1
 CYLC_TASK_CYCLE_POINT              # Cycle point, e.g. 20110511T1800Z
 ISODATETIMEREF                     # Reference time for the `isodatetime` command,
                                    #   defined with the value of CYLC_TASK_CYCLE_POINT
                                    #   when in any datetime cycling mode
 
-CYLC_TASK_NAME                     # Job's task name, e.g. t1
-CYLC_TASK_ID                       # Task instance identifier CYCLE-POINT/TASK-NAME
-                                   #   e.g. 20110511T1800Z/t1
-
 CYLC_TASK_SUBMIT_NUMBER            # Job's submit number, e.g. 1,
                                    #   increments with every submit
 CYLC_TASK_TRY_NUMBER               # Number of execution tries, e.g. 1
                                    #   increments with automatic execution retry delays.
 CYLC_TASK_FLOW_NUMBERS             # Flows this task belongs to, e.g. 1,2
 
 CYLC_TASK_LOG_DIR                  # Location of the job log directory
-                                   #   e.g. ~/cylc-run/foo/log/job/20110511T1800Z/t1/01/
+                                   #   e.g. ~/cylc-run/foo/run1/log/job/20110511T1800Z/t1/01/
 CYLC_TASK_LOG_ROOT                 # The job script path
-                                   #   e.g. ~/cylc-run/foo/log/job/20110511T1800Z/t1/01/job
+                                   #   e.g. ~/cylc-run/foo/run1/log/job/20110511T1800Z/t1/01/job
+CYLC_TASK_SHARE_CYCLE_DIR          # Cycle point-specific shared directory for this task.
+                                   #   e.g. ~/cylc-run/foo/run1/share/cycle/20110511T1800Z
 CYLC_TASK_WORK_DIR                 # Location of task work directory (see below)
-                                   #   e.g. ~/cylc-run/foo/work/20110511T1800Z/t1
-CYLC_TASK_SHARE_CYCLE_DIR          # The share/cycle/<cycle-point> directory
-                                   # for this task.
+                                   #   e.g. ~/cylc-run/foo/run1/work/20110511T1800Z/t1
 
 CYLC_TASK_NAMESPACE_HIERARCHY      # Linearised family namespace of the task,
                                    #   e.g. root postproc t1
@@ -65,4 +68,4 @@ CYLC_TASK_SSH_LOGIN_SHELL          # With "ssh" communication, if set to "True",
                                    #   use login shell on workflow host
 
 CYLC_TASK_PARAM_<param>            # If this task is a parameterized task,
-                                   # the value of the parameter named <param>
+                                   #   the value of the parameter named <param>

src/user-guide/writing-workflows/jinja2.rst

@@ -159,7 +159,7 @@ installed workflow at run time:
 .. table::
 
    =======================    ==============
-   CYLC_WORKFLOW_LOG_DIR      Workflow log sub-directory
+   CYLC_WORKFLOW_LOG_DIR      Workflow scheduler's log directory
    CYLC_WORKFLOW_SHARE_DIR    Workflow share sub-directory
    CYLC_WORKFLOW_WORK_DIR     Workflow work sub-directory
    =======================    ==============