Command help tweak.

cylc/flow/scripts/set.py

@@ -18,21 +18,35 @@
 
 """cylc set [OPTIONS] ARGS
 
-Intervene in task status in a running workflow.
+Override task status in a running workflow.
 
-By default, set all required outputs in specified tasks.
-(Note this won't set `succeeded` if it is not a required output!)
+By default (no options) this command sets all required outputs in target tasks.
+(Note this won't set the `succeeded` output if it is not a required output!)
 
-1. Satisfy task prerequisites (specify as <point>/<task-name>:<message>)
- - this affects task readiness to run
- - it brings tasks into the active window, with assigned flow membership
-    e.g. to begin checking clock triggers, xtriggers, and clock expiry
+With `--pre`, bring tasks into the active window with specified prequisites,
+if any, satisfied. This affects task readiness to run. It does not override
+clock triggers, xtriggers, or task hold.
 
-2. Complete task outputs (specify by the output label used in the graph)
- - affects task completion status
- - sets the prerequisites of tasks that depend on those outputs
- - sets implied outputs to (started implies submitted; succeeded and failed
-   imply started; custom outputs and expired do not imply any other outputs)
+With `--out`, complete specified outputs. This affects task completion.
+It also sets the prerequisites of downstream tasks that depend on those outputs,
+and any implied outputs (started implies submitted; succeeded and failed imply
+started; custom outputs and expired do not imply any other outputs).
+
+Examples:
+
+Satisfy all required outputs of `3/bar`:
+  cylc set my-workflow//3/bar
+
+Satisfy the succeeded output of `3/bar`:
+  cylc set my-workflow//3/bar succeeded
+
+Bring `3/bar` to the active window with its dependence on `3/foo` satisfied:
+  cylc set --pre=3/foo:succeeded my-workflow//3/bar
+
+Bring `3/bar` to the active window with all prerequisites (if any satisfied)
+to start checking on clock and xtriggers, and task expiry:
+
+  cylc set --pre=all my-workflow//3/bar
 
 """