Update 02-1st-example.md

_episodes/02-1st-example.md

@@ -13,25 +13,28 @@ keypoints:
 - "Input values are specified in a separate YAML file."
 - "The tool description and input files are provided as arguments to a CWL runner."
 ---
-The simplest "hello world" program.  This accepts one input parameter, writes a message to the terminal or job log, and produces no permanent output. CWL documents are written in [JSON][json] or [YAML][yaml], or a mix of the two.
+The simplest "hello world" program.  This accepts one input parameter, writes a message to the terminal or job log, and produces
+no permanent output. CWL documents are written in [JSON][json] or [YAML][yaml], or a mix of the two.
 
-First, create a file called 1st-tool.cwl, containing the boxed text below. It will help you to use a text editor that can be specified to produce text in YAML or JSON. Whatever text editor you use, the indents you see should not be created using tabs.
+First, create a file called `1st-tool.cwl`, containing the boxed text below. It will help you to use a text editor that can be
+specified to produce text in YAML or JSON. Whatever text editor you use, the indents you see should not be created using tabs.
 
 *1st-tool.cwl*
 ~~~
 {% include cwl/02-1st-example/1st-tool.cwl %}
 ~~~
 {: .source}
 
-Next, use a YAML or JSON object in a separate file to describe the input of a run:
+Next, create a file called `echo-job.yml`, containing the following boxed text, which will describe the input of a run:
 
 *echo-job.yml*
 ~~~
 {% include cwl/02-1st-example/echo-job.yml %}
 ~~~
 {: .source}
 
-Now, invoke `cwl-runner` with the tool wrapper and the input object on the command line:
+Now, invoke `cwl-runner` with the tool wrapper `1st-too.cwl` and the input object echo-job.yml on the command line. The command
+is  `cwl-runner 1st-tool.cwl echo-job.yml`. The boxed text below shows this command and the expected output.
 
 ~~~
 $ cwl-runner 1st-tool.cwl echo-job.yml
@@ -45,22 +48,27 @@ Final process status is success
 ~~~
 {: .output}
 
-What's going on here?  Let's break it down:
+The command `cwl-runner 1st-tool.cwl echo-job.yml` is an example of a general form that you will often come across while using
+CWL. The general form is `cwl-runner [tool-or-workflow-description] [input-job-settings]`
+
+What's going on here?  Let's break down the contents of `1st-tool.cwl`:
 
 ~~~
 cwlVersion: v1.0
 class: CommandLineTool
 ~~~
 {: .source}
 
-The `cwlVersion` field indicates the version of the CWL spec used by the document.  The `class` field indicates this document describes a command line tool.
+The `cwlVersion` field indicates the version of the CWL spec used by the document.  The `class` field indicates this document
+describes a command line tool.
 
 ~~~
 baseCommand: echo
 ~~~
 {: .source}
 
-The `baseCommand` provides the name of program that will actually run (`echo`)
+The `baseCommand` provides the name of program that will actually run (`echo`). [`echo`] is a built-in program in the bash and
+C shells.
 
 ~~~
 inputs:
@@ -71,7 +79,9 @@ inputs:
 ~~~
 {: .source}
 
-The `inputs` section describes the inputs of the tool.  This is a list of input parameters and each parameter includes an identifier, a data type, and optionally an `inputBinding` which describes how this input parameter should appear on the command line.  In this example, the `position` field indicates where it should appear on the command line.
+The `inputs` section describes the inputs of the tool.  This is a list of input parameters and each parameter includes an
+identifier, a data type, and optionally an `inputBinding` which describes how this input parameter should appear on the command
+line.  In this example, the `position` field indicates where it should appear on the command line.
 
 ~~~
 outputs: []
@@ -80,5 +90,8 @@ outputs: []
 
 This tool has no formal output, so the `outputs` section is an empty list.
 
-[json]: https://json.org
+[json]: http://json.org
+[yaml]: http://yaml.org
+[echo]: http://www.linfo.org/echo.html
+
 {% include links.md %}