Improve documentation ECFLOW-1996

docs/release_notes/version_5.10.rst

@@ -13,7 +13,7 @@ Version 5.10.0
 REST API
 --------
 
-- **New feature**: a new HTTP server provides access to a running ecFlow server via a REST API. This is still experimental and subject to change, but if you'd like to have a look, the documentation is here: :ref:`rest_api`
+- **New feature**: a new HTTP server provides access to a running ecFlow server via a REST API. This is still experimental and subject to change, but if you'd like to have a look, the documentation is :ref:`here <rest_api>`.
 
 ecFlowUI
 --------

docs/rest_api.rst

@@ -1,5 +1,7 @@
 .. _rest_api:
 
+REST API
+////////
 
 ..
    This reStructured Text file uses the following convention:
@@ -10,10 +12,6 @@
      ^ for subsubsections
      " for paragraphs
 
-
-REST API
-//////////////////////
-
 .. caution:: 
   ecFlow's REST API is experimental, and its details are subject to change. The documentation reflects its current operation.
 

docs/ug/user_manual/text_based_suite_definition/dependencies/cron/index.rst

@@ -6,8 +6,15 @@ cron
 A :term:`cron` defines a time dependency for a :term:`node`, similar to :term:`time`,
 but one that will be repeated indefinitely.
 
-When a node with a :term:`cron` completes it is :term:`queued` immediately, meaning that the suite
-will never complete, and the output will not be not directly accessible through :term:`ecflow_ui`
+.. warning::
+
+    A suite holding a node with a :term:`cron` attribute will **never** reach status *complete*.
+
+    A node with a :term:`cron` attribute is immediately set to :term:`queued` after completion.
+    In practice, this means that nodes containing a :term:`cron` attribute, and enveloping suites,
+    do not reach status *complete*, and their output is not be directly accessible through :term:`ecflow_ui`.
+
+    It is **highly discouraged** to create completion :term:`triggers <trigger>` on nodes/suites containing :term:`cron` attributes.
 
 If the task aborts, the :term:`ecflow_server` will not schedule it again.
 

docs/ug/user_manual/text_based_suite_definition/dependencies/date.rst

@@ -5,13 +5,24 @@ date
 
 This defines a date dependency for a node. There can be multiple date
 dependencies. The European format is used for dates, which is:
-**dd.mm.yy** as in 31.12.2012. Any of the three number fields can be
-expressed with a wildcard \* **to mean any valid value. Thus,
-01.*.\*** means the first day of every month of every year.
+**dd.mm.yyyy** as in ``31.12.2012``. Any of the three numeric fields can be
+expressed with a wildcard \* to mean any valid value. For example,
+``01.*.*`` can be used to represent the first day of every month of every year.
 
-Currently, you cannot specify a range of values for any of the three
-number fields in a date, See :ref:`text_based_def_day` for a way to specify the first seven
-days.
+.. warning::
+
+    A suite holding a node with a :term:`date` attribute may **never** reach status *complete*.
+
+    A node with a :term:`date` attribute is immediately set to :term:`queued` after completion.
+    In practice, this means that nodes containing a :term:`date` attribute, and enveloping suites,
+    only reach status *complete* when all specified date values have been exhausted -- which might be **never**.
+
+    **Extreme care** is advised when creating completion :term:`triggers <trigger>` on nodes/suites
+    containing :term:`date` attributes.
+
+
+Currently, a range of values cannot be used to specify any of the three numeric fields in a date.
+See :ref:`text_based_def_day` for a way to specify the first seven days.
 
 .. code-block:: shell
 
@@ -28,11 +39,11 @@ There are two kinds of clocks:
 
 - Hybrid clocks: A hybrid clock is a complex notion: the date and time are not connected. The date has a fixed value during the complete execution of the suite. This will be mainly used in cases where the suite does not complete in less than 24 hours. This guarantees that all the tasks of this suite are using the same date. On the other hand, the time follows the time of the machine.
 
-Once a suite is complete, it is repeated automatically, with the next
-date. The value of the date is contained in the ecFlow variable
-ECF_DATE, and the value of the time is in ECF_TIME. ECF_CLOCK contains
-other information such as the day of week. A job should always use the
-ecFlow variables, and not directly access the system date.
+The value of the date is contained in the ecFlow variable
+``ECF_DATE``, and the value of the time is in variable ``ECF_TIME``.
+The variable ``ECF_CLOCK`` contains other information such as the day of week.
+A well designed job should always use these ecFlow variables, and never directly
+access the system date.
 
 If a hybrid clock is defined for a suite, any node held by a date
 dependency will be set to complete at the beginning of the suite,