Improve events docs (#857)

Author: MetRonnie

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

@@ -653,14 +653,14 @@ as complete (and with the ``--flow`` option, if needed to make a specific
 Task Event Handling
 -------------------
 
-Task event handlers allow configured commands to run when task events occur.
+Task event handlers allow configured commands to run when task events occur,
+e.g. ``submitted`` and ``failed``.
 
-.. note::
-
-   Cylc supports workflow events e.g. ``startup`` and ``shutdown``
-   and task events e.g. ``submitted`` and ``failed``.
+.. admonition:: Not to be confused with
+   :class: tip
 
-   See also :ref:`user_guide.scheduler.workflow_event_handling`.
+   For *workflow* events, e.g. ``startup`` and ``shutdown``, see
+   :ref:`user_guide.scheduler.workflow_event_handling`.
 
 Event handlers can be used to send a message, raise an alarm, or whatever you
 like. They can even call ``cylc`` commands to intervene in the workflow.
@@ -679,42 +679,53 @@ Event handlers can be stored in the workflow ``bin`` directory, or anywhere in
 They should return quickly to avoid tying up the scheduler process pool -
 see :ref:`Managing External Command Execution`.
 
+.. _user_guide.runtime.task_event_handling.list:
 
-.. _user_guide.runtime.task_event_handling.event_specific_handlers:
-
-Event-Specific Handlers
-^^^^^^^^^^^^^^^^^^^^^^^
+List Of Task Events
+^^^^^^^^^^^^^^^^^^^
 
-Event-specific handlers are configured by ``<event> handlers``
-under :cylc:conf:`[runtime][<namespace>][events]`, where ``<event>``
-can be:
+.. cylc-scope:: flow.cylc[runtime][<namespace>]
 
 .. |br| raw:: html
 
      <br>
 
-
 .. table::
 
    =========================================  ================================
    Event                                      Description
    =========================================  ================================
    submitted                                  job submitted
-   submission retry                           job submission failed but will retry later
-   submission failed                          job submission failed
+   submission retry                           job submission failed but will retry after the configured :cylc:conf:`submission retry delays`
+   submission failed                          job submission failed and no retries are configured or remaining
    started                                    job started running
-   retry                                      job failed but will retry later
-   failed                                     job failed
+   retry                                      job failed but will retry after the configured :cylc:conf:`execution retry delays`
+   failed                                     job failed and no retries are configured or remaining
    succeeded                                  job succeeded
-   submission timeout                         job timed out in the ``submitted`` state
-   execution timeout                          job timed out in the ``running`` state
+   submission timeout                         job exceeded the :cylc:conf:`[events]submission timeout` while in the ``submitted`` state
+   execution timeout                          job exceeded the :cylc:conf:`[events]execution timeout` while in the ``running`` state
    warning                                    scheduler received a message of severity WARNING from job
    critical                                   scheduler received a message of severity CRITICAL from job
    custom                                     scheduler received a message of severity CUSTOM from job |br| (note: literally, the word ``CUSTOM``)
    expired                                    task expired and will not submit (too far behind)
    late                                       task running later than expected
    =========================================  ================================
 
+Any of a task's :term:`custom outputs <custom output>` are also valid event
+names.
+
+.. cylc-scope::
+
+
+.. _user_guide.runtime.task_event_handling.event_specific_handlers:
+
+Event-Specific Handlers
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Event-specific handlers are configured by ``<event> handlers``
+under :cylc:conf:`[runtime][<namespace>][events]`, where ``<event>``
+can be any in the table above.
+
 Values should be a list of commands, command lines, or command line templates
 (see below) to call if the specified event is triggered.
 
@@ -730,8 +741,8 @@ Alternatively you can configure a list of generic event :cylc:conf:`handlers` to
 for configured :cylc:conf:`handler events`.
 
 :cylc:conf:`handler events`
-   A list of events which may include any of the above
-   events (e.g. ``submission failed`` or ``warning``) or
+   A list of events which may include any of the events in the table above
+   (e.g. ``submission failed`` or ``warning``) or
    any of a task's :term:`custom outputs <custom output>`.
 :cylc:conf:`handlers`
    A list of commands to be run for these events.

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

@@ -15,13 +15,14 @@ workflows.
 Workflow Events
 ---------------
 
-There are two types of event in Cylc:
+Workflow events, e.g. ``startup`` and ``shutdown``, pertain to the
+:term:`scheduler`.
 
-* workflow events e.g. ``startup`` and ``shutdown``, which pertain to the :term:`scheduler`
-* task events e.g. ``submitted`` and ``failed``, which pertain to :term:`tasks <task>`.
+.. admonition:: Not to be confused with
+   :class: tip
 
-This section covers workflow events, for
-task events see :ref:`user_guide.runtime.task_event_handling`.
+   For :term:`task` events, e.g. ``submitted`` and ``failed``, see
+   :ref:`user_guide.runtime.task_event_handling`.
 
 .. rubric:: Event Handlers
 
@@ -33,15 +34,19 @@ run when workflow events occur. These can be configured by:
 
 .. rubric:: Abort On Event
 
-As well as event handlers, you can tell the scheduler to abort (i.e., shut down
-immediately with error status) on certain workflow events, using the
+As well as event handlers, you can tell the scheduler to shut down
+immediately (with error status) on certain workflow events, using the
 ``abort on ...`` configurations.
 
 .. rubric:: Configuration
 
 Some workflow events have related configurations e.g. for setting the timeout.
 
-.. rubric:: List of workflow events:
+
+.. _user_guide.scheduler.workflow_events.list:
+
+List of workflow events
+^^^^^^^^^^^^^^^^^^^^^^^
 
 .. cylc-scope:: global.cylc[scheduler][events]