Separate commands and output (#238)

* Separate commands and output

* Use tool description, not tool wrapper

Author: kinow

README.md

@@ -28,6 +28,9 @@ or links to Markdown pages). For simple HTML links (e.g. `< href=>` or
 markdown external links) pull request reviewers must verify that links
 are still working after the change.
 
+Use “tool description” not “tool wrapper” for describing the first argument
+given to the `cwl-runner` or `cwltool` commands.
+
 ### Code examples
 
 To include code into a Markdown file you have two options. For external files use

src/topics/additional-arguments-and-parameters.md

@@ -21,11 +21,15 @@ instead.
 :caption: "`arguments-job.yml`"
 ```
 
-Now create a sample Java file and invoke `cwl-runner` providing the tool wrapper
-and the input object on the command line:
+Next, create a sample Java file to use with the command-line tool.
 
 ```{code-block} console
 $ echo "public class Hello {}" > Hello.java
+```
+
+And now invoke `cwl-runner` providing the tool description and the input object on the command line:
+
+```{code-block} console
 $ cwl-runner arguments.cwl arguments-job.yml
 [job arguments.cwl] /tmp/tmpwYALo1$ docker \
  run \

src/topics/creating-files-at-runtime.md

@@ -51,7 +51,7 @@ which is YAML quoting syntax, and means that you are using a multiline string
 See the [YAML Guide](../topics/yaml-guide.md#maps) for more about the formatting.
 ```
 
-Now invoke `cwl-runner` with the tool wrapper and the input object on the
+Now invoke `cwl-runner` with the tool description and the input object on the
 command line:
 
 ```{code-block} console

src/topics/environment-variables.md

@@ -15,7 +15,7 @@ the tool using `EnvVarRequirement`.
 :caption: "`echo-job.yml`"
 ```
 
-Now invoke `cwl-runner` with the tool wrapper and the input object on the
+Now invoke `cwl-runner` with the tool description and the input object on the
 command line:
 
 ```{code-block} console

src/topics/file-formats.md

@@ -49,7 +49,7 @@ ___Note:___ To follow the example below, you need to download the example input
 wget https://github.com/common-workflow-language/user_guide/raw/main/_includes/cwl/16-file-formats/file-formats.bam
 ```
 
-Now invoke `cwl-runner` with the tool wrapper and the input object on the
+Now invoke `cwl-runner` with the tool description and the input object on the
 command line:
 
 ```{code-block} console

src/topics/inputs.md

@@ -35,7 +35,7 @@ Create a file called inp-job.yml:
 Notice that "example_file", as a `File` type, must be provided as an
 object with the fields `class: File` and `path`.
 
-Next, create a whale.txt using [touch] by typing `touch whale.txt` on the command line and then invoke `cwl-runner` with the tool wrapper and the input object on the command line, using the command `cwl-runner inp.cwl inp-job.yml`. The following boxed text describes these two commands and the expected output from the command line:
+Next, create a whale.txt using [touch] by typing `touch whale.txt` on the command line and then invoke `cwl-runner` with the tool description and the input object on the command line, using the command `cwl-runner inp.cwl inp-job.yml`. The following boxed text describes these two commands and the expected output from the command line:
 
 ```{code-block} console
 $ touch whale.txt
@@ -157,7 +157,7 @@ the type name to indicate that input parameter is array of that type.
 :name: array-inputs-job.yml
 ```
 
-Now invoke `cwl-runner` providing the tool wrapper and the input object
+Now invoke `cwl-runner` providing the tool description and the input object
 on the command line:
 
 ```{code-block} console

src/topics/outputs.md

@@ -35,11 +35,16 @@ any subsequent elements are mandatory command line arguments
 :name: tar-job.yml
 ```
 
-Next, create a tar file for the example and invoke `cwl-runner` with the tool
-wrapper and the input object on the command line:
+Next, create a tar file for the example.
 
 ```{code-block} console
 $ touch hello.txt && tar -cvf hello.tar hello.txt
+hello.txt
+```
+
+And now invoke `cwl-runner` with the tool description and the input object on the command line:
+
+```{code-block} console
 $ cwl-runner tar.cwl tar-job.yml
 [job tar.cwl] /tmp/tmpqOeawQ$ tar \
     --extract --file \
@@ -89,7 +94,7 @@ stdout` on the corresponding output parameter.
 :caption: "`echo-job.yml`"
 ```
 
-Now invoke `cwl-runner` providing the tool wrapper and the input object
+Now invoke `cwl-runner` providing the tool description and the input object
 on the command line:
 
 ```{code-block} console
@@ -126,7 +131,7 @@ You can also capture multiple output files into an array of files using `glob`.
 :name: array-outputs-job.yml
 ```
 
-Now invoke `cwl-runner` providing the tool wrapper and the input object
+Now invoke `cwl-runner` providing the tool description and the input object
 on the command line:
 
 ```{code-block} console

src/topics/parameter-references.md

@@ -22,7 +22,7 @@ the file to extract.
 :name: tar-param-job.yml
 ```
 
-Create your input files and invoke `cwl-runner` with the tool wrapper and the
+Create your input files and invoke `cwl-runner` with the tool description and the
 input object on the command line:
 
 ```{code-block} console

src/topics/staging-input-files.md

@@ -17,7 +17,7 @@ input file from its leading directory path.
 :caption: "`arguments-job.yml`"
 ```
 
-Now invoke `cwl-runner` with the tool wrapper and the input object on the
+Now invoke `cwl-runner` with the tool description and the input object on the
 command line:
 
 ```{code-block} console

src/topics/using-containers.md

@@ -49,7 +49,7 @@ the name of the container image (you can even specify the tag, which is good ide
 best practises when using containers for reproducible research). In this case we have
 used a container called `node:slim`.
 
-Provide a "hello.js" and invoke `cwl-runner` providing the tool wrapper and the
+Provide a "hello.js" and invoke `cwl-runner` providing the tool description and the
 input object on the command line:
 
 ```{code-block} console