Tweak scan CLI help [skip ci]

cylc/flow/scripts/scan.py

@@ -17,15 +17,23 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 """cylc scan [OPTIONS]
 
-List Cylc workflows.
+List workflows.
 
-By default this shows only running or paused workflows.
+By default, list running (or paused) workflows as recorded in contact files:
+  ~/cylc-run/<Workflow-ID>/.service/contact.
+
+Schedulers may occasionally leave contact files behind after an unclean shut
+down. With the `--ping` option, scan will attempt to connect to the scheduler
+and will remove the contact file if the workflow is not running.
+
+Source workflows (--source), and installed ones that are not currently
+running (--state=stopped) can also be listed.
 
 Examples:
-  # list all "active" workflows (i.e. running or paused)
+  # list all active workflows (i.e. running or paused)
   $ cylc scan
 
-  # show more information about these workflows
+  # show more information about active workflows (connects to the schedulers)
   $ cylc scan -t rich
 
   # don't rely on colour for job state totals
@@ -41,11 +49,11 @@
   # filter workflows by name
   $ cylc scan --name '^f.*'  # show only flows starting with "f"
 
-  # list source workflows in a tree
+  # list source workflows in tree format
   # (looks in the dirs configured by "global.cylc[install]source dirs")
   $ cylc scan --source -t tree
 
-  # get results in JSON format
+  # get contact file contents in JSON format
   $ cylc scan -t json
 """
 
@@ -207,7 +215,7 @@ def get_option_parser() -> COP:
             'Set the output format.'
             ' (rich: multi-line, human readable)'
             ' (plain: single-line)'
-            ' (json: machine readable)'
+            ' (json: machine readable contact file contents)'
             ' (tree: display registration hierarchy as a tree)'
             ' (name: just show flow names, machine readable)'
         ),