Update docs for trigger-when-paused.

src/glossary.rst

@@ -1151,7 +1151,11 @@ Glossary
 
    pause
       When a :term:`workflow` is "paused" the :term:`scheduler` is still
-      running but it will not submit any new jobs.
+      running but it will not automatically submit new jobs.
+
+      You can still manually :term:`trigger` tasks in a paused workflow. By
+      default they will run once the workflow is resumed, or immediately
+      with the ``--now`` trigger option.
 
       This can be useful if you want to make a change to a running workflow.
 
@@ -1247,7 +1251,11 @@ Glossary
          :term:`Tasks <task>` can be :term:`held <hold>` with ``cylc hold`` and
          :term:`released <release>` with ``cylc release``.
 
-         When a workflow is resumed, any held tasks remain held.
+         When a paused workflow is resumed, any held tasks remain held.
+
+         If a running task is held its running job is not affected, but it will
+         not submit any more jobs (such as automatic :term:`retries <retry>`)
+         until released. The children of held tasks are not automatically held.
 
 
    release
@@ -1487,6 +1495,9 @@ Glossary
       :term:`custom <custom output>` task outputs. In the latter case they
       are known as :term:`message triggers <message trigger>`.
 
+      The term "trigger" also refers the action of manually triggering
+      a task to run, via the ``cylc trigger`` command or the GUI. 
+
 
    message trigger
       A message trigger is a :term:`trigger` based on a

src/user-guide/interventions/index.rst

@@ -441,18 +441,17 @@ but specify the "failed" output rather than
 "succeeded".
 
 
-Hold The Workflow And Trigger Tasks One By One
-----------------------------------------------
+Pause The Workflow And Trigger Tasks One By One
+-----------------------------------------------
 
 :Example:
-   I want to hold back the workflow while I manually run one or more tasks
+   I want to pause the workflow while I manually run one or more tasks
    to fix a problem or test a task.
 
 :Solution:
-   * Hold all tasks after a specified cycle.
-   * Trigger the task(s) you want to run.
-   * When you're done triggering, release the held tasks to allow the workflow
-     to continue.
+   * Pause the workflow.
+   * Trigger the task(s) you want to run, with the ``--now`` option.
+   * When you're done triggering, resume (unpause) the workflow.
 
 .. tab-set::
 
@@ -467,24 +466,25 @@ Hold The Workflow And Trigger Tasks One By One
 
       .. code-block:: console
 
-         $ # hold all tasks after the cycle "2000"
-         $ cylc hold --after=2000 <workflow>
+         $ # pause the workflow
+         $ cylc pause <workflow>
 
          $ # trigger the task(s) you want to run
-         $ cylc trigger <workflow>//<cycle>/<task>
+         $ cylc trigger --now <workflow>//<cycle>/<task>
 
-         $ # release the "hold point" to allow the workflow to continue
-         $ cylc release --all <workflow>
+         $ # resume (unpause) the workflow to continue
+         $ cylc play <workflow>
 
 .. note::
 
    The difference between the workflow "paused" state and the task "held" state:
 
    Workflow Pause
-      When a workflow is :term:`paused <pause>`, no new jobs will be submitted.
-      This gives you an opportunity to make changes to the workflow, however, if
-      you trigger tasks, they will not run until the workflow is resumed.
+      When a workflow is :term:`paused <pause>` new jobs will not be submitted
+      automatically, but you can still trigger tasks manually.
+      This gives you an opportunity to make changes to the workflow.
 
    Task Hold
-      When a task is :term:`held <hold>`, then it will not submit (if ready to
-      submit) until released.
+      When a task is :term:`held <hold>` it will not submit a job until released.
+      Holding a running task does not affect its existing job, but it will not
+      submit any new jobs (such as :term:`retries <retry>`) until released.