cmd/cue: refer to 'workflow commands' instead of 'commands'

https://cuelang.org/cl/1185798 shows how tricky it is to refer to
commands that are declared as part of a _tool.cue "thing" without
creating serious confusion with other, well, commands.

In patchset 4, Jonathan tried out the term "tool command". This is a bit
vague to my mind, but also not as strong as "workflow command".
"Workflow" is a better term, more suited to the fact that these commands
are part of a (data-driven) workflow.

In support of https://cuelang.org/cl/1185798, I'm proposing this change,
to amend all references in the cmd/cue documentation from the simple
"command" (when it means a command in a _tool.cue fiel) to "workflow
command".

The intentional "clash" with other commands, like export, comes (as far
as I can recall) from the fact that both can and do take inputs
(although _tool.cue commands are much more limited: see
https://cuelang.org/issue/1325). Whilst there is a non-zero benefit to
such overloading of the term, the confusion it creates is to my mind far
greater. With or without any improvements suggested in
https://cuelang.org/issue/1325 we can stil say that "workflow commands"
accept inputs similar to "cue commands" (which can then be references to
the cmd/cue commands).

Signed-off-by: Paul Jolly <[email protected]>
Change-Id: Iccc181e607163ea995c52861b421093a099c0b1d
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1187654
TryBot-Result: CUEcueckoo <[email protected]>
Unity-Result: CUE porcuepine <[email protected]>
Reviewed-by: Daniel Martí <[email protected]>

cmd/cue/cmd/cmd.go

@@ -28,15 +28,15 @@ import (
 func newCmdCmd(c *Command) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "cmd <name> [inputs]",
-		Short: "run a user-defined shell command",
+		Short: "run a user-defined workflow command",
 		Long: `cmd executes the named command for each of the named instances.
 
-Commands define actions on instances. For example, they may
-specify how to upload a configuration to Kubernetes. Commands are
-defined directly in tool files, which are regular CUE files
-within the same package with a filename ending in _tool.cue.
-These are typically defined at the module root so that they apply
-to all instances.
+Workflow commands define actions on instances. For example, they
+may specify how to upload a configuration to Kubernetes. Workflow
+commands are defined directly in tool files, which are regular
+CUE files within the same package with a filename ending in
+_tool.cue.  These are typically defined at the module root so
+that they apply to all instances.
 
 Each command consists of one or more tasks. A task may, for
 example, load or write a file, consult a user on the command
@@ -57,8 +57,8 @@ Available tasks can be found in the package documentation at
 
 Examples:
 
-In this simple example, we define a command called "hello",
-which declares a single task called "print" which uses
+In this simple example, we define a workflow command called
+"hello", which declares a single task called "print" which uses
 "tool/exec.Run" to execute a shell command that echos output to
 the terminal:
 
@@ -78,7 +78,7 @@ the terminal:
 	}
 	EOF
 
-We run the "hello" command like this:
+We run the "hello" workflow command like this:
 
 	$ cue cmd hello
 	Hello World! Welcome to Amsterdam.
@@ -87,12 +87,13 @@ We run the "hello" command like this:
 	Hello Jan! Welcome to Amsterdam.
 
 
-In this example we declare the "prompted" command which has four
-tasks. The first task prompts the user for a string input. The
-second task depends on the first, and echos the response back to
-the user with a friendly message. The third task pipes the output
-from the second to a file. The fourth task pipes the output from
-the second to standard output (i.e. it echos it again).
+In this example we declare the "prompted" workflow command which
+has four tasks. The first task prompts the user for a string
+input. The second task depends on the first, and echos the
+response back to the user with a friendly message. The third task
+pipes the output from the second to a file. The fourth task pipes
+the output from the second to standard output (i.e. it echos it
+again).
 
 	package foo
 
@@ -132,7 +133,7 @@ the second to standard output (i.e. it echos it again).
 		}
 	}
 
-Run "cue help commands" for more details on tasks and commands.
+Run "cue help commands" for more details on tasks and workflow commands.
 `,
 		RunE: mkRunE(c, func(cmd *Command, args []string) error {
 			// The behavior when there's no known subcommand is different

cmd/cue/cmd/help.go

@@ -622,15 +622,15 @@ The following variables are supported:
 var commandsHelp = &cobra.Command{
 	Use:   "commands",
 	Short: "user-defined commands",
-	Long: `Commands define actions on instances. For example, they may
-specify how to upload a configuration to Kubernetes. Commands are
-defined directly in tool files, which are regular CUE files
-within the same package with a filename ending in _tool.cue.
-These are typically defined at the module root so that they apply
-to all instances.
-
-Each command consists of one or more tasks. A task may, for
-example, load or write a file, consult a user on the command
+	Long: `Workflow commands define actions on instances. For example, they
+may specify how to upload a configuration to Kubernetes. Workflow
+commands are defined directly in tool files, which are regular
+CUE files within the same package with a filename ending in
+_tool.cue.  These are typically defined at the module root so
+that they apply to all instances.
+
+Each workflow command consists of one or more tasks. A task may,
+for example, load or write a file, consult a user on the command
 line, fetch a web page, and so on. Each task has inputs and
 outputs. Outputs are typically filled out by the task
 implementation as the task completes.
@@ -646,12 +646,10 @@ Available tasks can be found in the package documentation at
 
 	https://pkg.go.dev/cuelang.org/go/pkg/tool?tab=subdirectories
 
-More on tasks can be found in the commands help topic.
-
 Examples:
 
-In this simple example, we define a command called "hello",
-which declares a single task called "print" which uses
+In this simple example, we define a workflow command called
+"hello", which declares a single task called "print" which uses
 "tool/exec.Run" to execute a shell command that echos output to
 the terminal:
 
@@ -671,7 +669,7 @@ the terminal:
 	}
 	EOF
 
-We run the "hello" command like this:
+We run the "hello" workflow command like this:
 
 	$ cue cmd hello
 	Hello World! Welcome to Amsterdam.
@@ -680,12 +678,13 @@ We run the "hello" command like this:
 	Hello Jan! Welcome to Amsterdam.
 
 
-In this example we declare the "prompted" command which has four
-tasks. The first task prompts the user for a string input. The
-second task depends on the first, and echos the response back to
-the user with a friendly message. The third task pipes the output
-from the second to a file. The fourth task pipes the output from
-the second to standard output (i.e. it echos it again).
+In this example we declare the "prompted" workflow command which
+has four tasks. The first task prompts the user for a string
+input. The second task depends on the first, and echos the
+response back to the user with a friendly message. The third task
+pipes the output from the second to a file. The fourth task pipes
+the output from the second to standard output (i.e. it echos it
+again).
 
 	package foo
 

cmd/cue/cmd/testdata/script/help.txtar

@@ -73,7 +73,7 @@ Usage:
   cue [command]
 
 Available Commands:
-  cmd            run a user-defined shell command
+  cmd            run a user-defined workflow command
   completion     Generate completion script
   def            print consolidated definitions
   eval           evaluate and print a configuration

cmd/cue/cmd/testdata/script/help_cmd.txtar

@@ -45,12 +45,12 @@ Run 'cue help cmd' for known subcommands.
 -- cue-help-cmd.stdout --
 cmd executes the named command for each of the named instances.
 
-Commands define actions on instances. For example, they may
-specify how to upload a configuration to Kubernetes. Commands are
-defined directly in tool files, which are regular CUE files
-within the same package with a filename ending in _tool.cue.
-These are typically defined at the module root so that they apply
-to all instances.
+Workflow commands define actions on instances. For example, they
+may specify how to upload a configuration to Kubernetes. Workflow
+commands are defined directly in tool files, which are regular
+CUE files within the same package with a filename ending in
+_tool.cue.  These are typically defined at the module root so
+that they apply to all instances.
 
 Each command consists of one or more tasks. A task may, for
 example, load or write a file, consult a user on the command
@@ -71,8 +71,8 @@ Available tasks can be found in the package documentation at
 
 Examples:
 
-In this simple example, we define a command called "hello",
-which declares a single task called "print" which uses
+In this simple example, we define a workflow command called
+"hello", which declares a single task called "print" which uses
 "tool/exec.Run" to execute a shell command that echos output to
 the terminal:
 
@@ -92,7 +92,7 @@ the terminal:
 	}
 	EOF
 
-We run the "hello" command like this:
+We run the "hello" workflow command like this:
 
 	$ cue cmd hello
 	Hello World! Welcome to Amsterdam.
@@ -101,12 +101,13 @@ We run the "hello" command like this:
 	Hello Jan! Welcome to Amsterdam.
 
 
-In this example we declare the "prompted" command which has four
-tasks. The first task prompts the user for a string input. The
-second task depends on the first, and echos the response back to
-the user with a friendly message. The third task pipes the output
-from the second to a file. The fourth task pipes the output from
-the second to standard output (i.e. it echos it again).
+In this example we declare the "prompted" workflow command which
+has four tasks. The first task prompts the user for a string
+input. The second task depends on the first, and echos the
+response back to the user with a friendly message. The third task
+pipes the output from the second to a file. The fourth task pipes
+the output from the second to standard output (i.e. it echos it
+again).
 
 	package foo
 
@@ -146,7 +147,7 @@ the second to standard output (i.e. it echos it again).
 		}
 	}
 
-Run "cue help commands" for more details on tasks and commands.
+Run "cue help commands" for more details on tasks and workflow commands.
 
 Usage:
   cue cmd <name> [inputs] [flags]

cmd/cue/cmd/testdata/script/help_cmd_flags.txtar

@@ -29,12 +29,12 @@ command: echo: {
 -- expect-stdout --
 cmd executes the named command for each of the named instances.
 
-Commands define actions on instances. For example, they may
-specify how to upload a configuration to Kubernetes. Commands are
-defined directly in tool files, which are regular CUE files
-within the same package with a filename ending in _tool.cue.
-These are typically defined at the module root so that they apply
-to all instances.
+Workflow commands define actions on instances. For example, they
+may specify how to upload a configuration to Kubernetes. Workflow
+commands are defined directly in tool files, which are regular
+CUE files within the same package with a filename ending in
+_tool.cue.  These are typically defined at the module root so
+that they apply to all instances.
 
 Each command consists of one or more tasks. A task may, for
 example, load or write a file, consult a user on the command
@@ -55,8 +55,8 @@ Available tasks can be found in the package documentation at
 
 Examples:
 
-In this simple example, we define a command called "hello",
-which declares a single task called "print" which uses
+In this simple example, we define a workflow command called
+"hello", which declares a single task called "print" which uses
 "tool/exec.Run" to execute a shell command that echos output to
 the terminal:
 
@@ -76,7 +76,7 @@ the terminal:
 	}
 	EOF
 
-We run the "hello" command like this:
+We run the "hello" workflow command like this:
 
 	$ cue cmd hello
 	Hello World! Welcome to Amsterdam.
@@ -85,12 +85,13 @@ We run the "hello" command like this:
 	Hello Jan! Welcome to Amsterdam.
 
 
-In this example we declare the "prompted" command which has four
-tasks. The first task prompts the user for a string input. The
-second task depends on the first, and echos the response back to
-the user with a friendly message. The third task pipes the output
-from the second to a file. The fourth task pipes the output from
-the second to standard output (i.e. it echos it again).
+In this example we declare the "prompted" workflow command which
+has four tasks. The first task prompts the user for a string
+input. The second task depends on the first, and echos the
+response back to the user with a friendly message. The third task
+pipes the output from the second to a file. The fourth task pipes
+the output from the second to standard output (i.e. it echos it
+again).
 
 	package foo
 
@@ -130,7 +131,7 @@ the second to standard output (i.e. it echos it again).
 		}
 	}
 
-Run "cue help commands" for more details on tasks and commands.
+Run "cue help commands" for more details on tasks and workflow commands.
 
 Usage:
   cue cmd <name> [inputs] [flags]