Tidy main command help. (#4973)

* Tidy man command help. [skip ci] Co-authored-by: Oliver Sanders <oliver.sanders@metoffice.gov.uk>
cylc · Jul 14, 2022 · d4938dd · d4938dd
1 parent 9f3eb59
commit d4938dd
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 46 deletions.
diff --git a/cylc/flow/scripts/cylc.py b/cylc/flow/scripts/cylc.py
@@ -46,32 +46,26 @@ def get_version(long=False):
 
 
 USAGE = f"""{cylc_header()}
-Cylc ("silk") orchestrates complex cycling (and non-cycling) workflows.
+Cylc ("silk") efficiently manages distributed cycling workflows.
+Cylc is Open Source software (GPL-3.0): see "cylc help license".
 
 Version:
-  $ cylc version --long           # print cylc-flow version and install path
+  $ cylc version --long
   {get_version(True)}
 
-Usage:
-  $ cylc help license             # view the Cylc license (GPL-3.0)
-  $ cylc help all                 # list all commands
-  $ cylc validate <workflow>      # validate a workflow configuration
-  $ cylc install <workflow>       # install a workflow
-  $ cylc play <workflow>          # run/resume a workflow
-  $ cylc scan                     # list all running workflows (by default)
-  $ cylc tui <workflow>           # view/control workflows in the terminal
-  $ cylc stop <workflow>          # stop a running workflow
-
-Command Abbreviation:
-  # Commands can be abbreviated as long as there is no ambiguity in
-  # the abbreviated command:
-  $ cylc trigger WORKFLOW//CYCLE/TASK    # trigger TASK in WORKFLOW
-  $ cylc trig WORKFLOW//CYCLE/TASK       # ditto
-  $ cylc tr WORKFLOW//CYCLE/TASK         # ditto
-  $ cylc t                               # Error: ambiguous command
+Quick Start:
+  $ cylc install <path>       # install a workflow
+  $ cylc play <workflow_id>   # run or resume a workflow
+  $ cylc stop <workflow_id>   # stop a workflow
+  $ cylc clean <workflow_id>  # delete an installed workflow
+  $ cylc gui                  # start the in-browser web UI
+  $ cylc tui <workflow_id>    # start the in-terminal UI
+
+  $ cylc help all             # see all cylc commands
+  $ cylc <command> --help     # specific command help
 
 Cylc IDs:
-  Cylc IDs take the form:
+  Workflows and tasks are identified by IDs of the form:
     workflow//cycle/task
 
   You can split an ID at the // so following two IDs are equivalent:
@@ -80,10 +74,15 @@ def get_version(long=False):
 
   IDs can be written as globs:
     *//                 # All workflows
-    workflow//*         # All cycles in "workflow"
-    workflow//cycle/*   # All tasks in "workflow" in "cycle"
+    workflow//*         # All cycle points in "workflow"
+    workflow//cycle/*   # All tasks in cycle point "cycle" of "workflow"
+
+  $ cylc help id        # More information on IDs
 
-  For more information type "cylc help id".
+Cylc commands can be abbreviated:
+  $ cylc trigger workflow//cycle/task    # trigger task in workflow
+  $ cylc trig workflow//cycle/task       # trigger task in workflow
+  $ cylc t                               # error: trigger or tui?
 """
 
 ID_HELP = '''
@@ -431,25 +430,6 @@ def cli_help():
     from colorama import init as color_init
     color_init(autoreset=True, strip=False)
     print(USAGE)
-    print('Selected Sub-Commands:')
-    print_command_list(
-        # print a short list of the main cylc commands
-        commands=[
-            'hold',
-            'install',
-            'kill',
-            'pause',
-            'play',
-            'release',
-            'scan',
-            'stop',
-            'trigger',
-            'tui',
-            'validate'
-        ],
-        indent=2
-    )
-    print('\nTo see all commands run: cylc help all')
     sys.exit(0)
 
 

diff --git a/cylc/flow/scripts/trigger.py b/cylc/flow/scripts/trigger.py
@@ -17,16 +17,16 @@
 
 """cylc trigger [OPTIONS] ARGS
 
-Trigger tasks - i.e. tell them to run even if they are not ready.
+Force tasks to run despite unsatisfied prerequisites.
 
 Triggering an unqueued waiting task queues it, regardless of prerequisites.
 
-Triggering a queued waiting task submits it, regardless of queue limiting.
+Triggering a queued task submits it, regardless of queue limiting.
 
-Triggering a submitted or running task has no effect (already triggered).
+Triggering an active task has no effect (it already triggered).
 
 Incomplete and active-waiting tasks in the n=0 window already belong to a flow.
-Triggering them queues them to run (or rerun) in the same flow;
+Triggering them queues them to run (or rerun) in the same flow.
 
 Beyond n=0, triggered tasks get all current active flow numbers by default, or
 specified flow numbers via the --flow option. Those flows - if/when they catch