Included documentation of secondary files

src/topics/inputs.md

@@ -11,7 +11,7 @@ and *null*; complex types are *array* and *record*; in addition there are
 special types *File*, *Directory* and *Any*.
 
 The following example demonstrates some input parameters with different
-types and appearing on the command line in different ways.
+types and how they can appear on the command line.
 
 First, create a file called `inp.cwl`, containing the following:
 
@@ -31,7 +31,7 @@ Create a file called `inp-job.yml`:
 
 ````{note}
 You can use `cwltool` to create a template input object. That saves you from having
-to type all the input parameters in a input object file:
+to type all the input parameters in an input object file:
 
 ```{runcmd} cwltool --make-template inp.cwl
 :working-directory: src/_includes/cwl/inputs
@@ -50,7 +50,7 @@ Next, create a whale.txt using [touch] by typing `touch whale.txt` on the comman
 $ touch whale.txt
 ```
 
-Now invoke `cwltool` with the tool description and the input object on the command line,
+Now, invoke `cwltool` with the tool description and the input object on the command line,
 using the command `cwltool inp.cwl inp-job.yml`. The following boxed text describes these
 two commands and the expected output from the command line:
 
@@ -67,8 +67,8 @@ the tools aren't accidentally accessing files that were not explicitly
 specified
 ```
 
-The field `inputBinding` is optional and indicates whether and how the
-input parameter should appear on the tool's command line.  If
+The field `inputBinding` is optional and indicates if and how the
+input parameter should appear on the tool's command line. If
 `inputBinding` is missing, the parameter does not appear on the command
 line.  Let's look at each example in detail.
 
@@ -80,9 +80,9 @@ example_flag:
     prefix: -f
 ```
 
-Boolean types are treated as a flag.  If the input parameter
+Boolean types are treated as a flag. If the input parameter
 "example_flag" is "true", then `prefix` will be added to the
-command line.  If false, no flag is added.
+command line. If false, no flag is added.
 
 ```cwl
 example_string:
@@ -92,9 +92,9 @@ example_string:
     prefix: --example-string
 ```
 
-String types appear on the command line as literal values.  The `prefix`
+String types appear on the command line as literal values. The `prefix`
 is optional, if provided, it appears as a separate argument on the
-command line before the parameter .  In the example above, this is
+command line before the parameter. In the example above, this is
 rendered as `--example-string hello`.
 
 ```cwl
@@ -107,9 +107,9 @@ example_int:
 ```
 
 Integer (and floating point) types appear on the command line with
-decimal text representation.  When the option `separate` is false (the
+decimal text representation. When the option `separate` is false (the
 default value is true), the prefix and value are combined into a single
-argument.  In the example above, this is rendered as `-i42`.
+argument. In the example above, this is rendered as `-i42`.
 
 
 ```cwl
@@ -121,17 +121,17 @@ example_file:
     position: 4
 ```
 
-File types appear on the command line as the path to the file.  When the
+File types appear on the command line as the path to the file. When the
 parameter type ends with a question mark `?` it indicates that the
-parameter is optional.  In the example above, this is rendered as
-`--file=/tmp/random/path/whale.txt`.  However, if the "example_file"
+parameter is optional. In the example above, this is rendered as
+`--file=/tmp/random/path/whale.txt`. However, if the "example_file"
 parameter were not provided in the input, nothing would appear on the
 command line.
 
-Input files are read-only.  If you wish to update an input file, you must
+Input files are read-only. If you wish to update an input file, you must
 [first copy it to the output directory](staging-input-files.md).
 
-The value of `position` is used to determine where parameter should
+The value of `position` is used to determine where the parameter should
 appear on the command line.  Positions are relative to one another, not
 absolute.  As a result, positions do not have to be sequential, three
 parameters with positions 1, 3, 5 will result in the same command
@@ -143,13 +143,91 @@ The `baseCommand` field will always appear in the final command line before the
 
 [touch]: http://www.linfo.org/touch.html
 
+### Documenting input parameters using `label` or `doc`
+
+`label` is a short, human-readable description for the parameter.
+
+```cwl
+inputs:
+  example_file:
+    type: File
+    label: Use case for label parameter
+    inputBinding:
+      position: 1
+```
+
+`doc` is a documentation string for the object, or an array of strings which should be concatenated.
+
+```cwl
+inputs:
+  example_file:
+    type: File
+    doc: This section demonstrates Optional fields on the Input Parameter 
+    inputBinding:
+      position: 1
+ ```
+
+ ````{note}
+ `label` and `doc` fields can also be used to document output parameters.
+ ````
+
+### Attaching Secondary files to the inputs file
+
+Secondary files are input files that should be staged in the same directory as the input files.
+The `secondaryFiles` parameter defines files or directories that can be automatically uploaded with the primary input file.
+For example, if the primary input is an HTML file (.html), an image file (.png or .jpg) could be included as a secondary file.
+
+The use of secondary files are optional for inputs. However, if secondary files are defined for an input file,
+they should exist. An implementation may fail workflow execution if an expected secondary file does not exist.
+
+When defining primary and secondary files in your CWL workflow, 
+use the input parameter to specify your primary files, and use the `secondaryFiles` parameter to define your secondary files.
+An implementation must include matching files and directories in the `secondaryFiles` parameter of the primary file.
+The following example demonstrates the `secondaryFiles` input parameter.
+
+```cwl
+inputs:
+  example_file:
+    type: File
+    inputBinding:
+      prefix: -e
+    secondaryFiles:
+      - .idx
+```
+
+If a value in `secondaryFiles` is a string that is not an expression, 
+it specifies that the following pattern should be applied to the path of the primary file 
+to yield a filename relative to the primary File:
+
+- If the string begins with one or more caret "^" characters, for each caret, remove the last file extension from the path(the last period `.` and all following characters), and append the remainder of the string to the end of the file path.
+
+```cwl
+inputs:
+  example_file:
+    type: File
+    inputBinding:
+      prefix: -e
+    secondaryFiles: 
+      - ^.idx
+```
+
+assuming the primary file above has a .txt extension (`example_file.txt`), the secondary file will be `example_file.idx`.
+
+````{note}
+Secondary files are only valid when `type` has a value `File`, or is an array of `items: File`.
+All listed secondary files must be present in the same directory as the primary file,
+since an implementation may fail workflow execution if a listed secondary file is not present.
+It is an error for file names to be duplicated in `secondaryFiles`.
+Secondary files can also be used for output files.
+````
+
 ## Array Inputs
 
 It is easy to add arrays of input parameters represented to the command
 line. There are two ways to specify an array parameter. First is to provide
 `type` field with `type: array` and `items` defining the valid data types
 that may appear in the array. Alternatively, brackets `[]` may be added after
-the type name to indicate that input parameter is array of that type.
+the type name to indicate that the input parameter is an array of that type.
 
 ```{literalinclude} /_includes/cwl/inputs/array-inputs.cwl
 :language: cwl
@@ -163,7 +241,7 @@ the type name to indicate that input parameter is array of that type.
 :name: array-inputs-job.yml
 ```
 
-Now invoke `cwltool` providing the tool description and the input object
+Now invoke `cwltool` by providing the tool description and the input object
 on the command line:
 
 ```{runcmd} cwltool array-inputs.cwl array-inputs-job.yml
@@ -191,7 +269,7 @@ You can specify arrays of arrays, arrays of records, and other complex types.
 ## Inclusive and Exclusive Inputs
 
 Sometimes an underlying tool has several arguments that must be provided
-together (they are dependent) or several arguments that cannot be provided
+together, (they are dependent) or several arguments that cannot be provided
 together (they are exclusive).  You can use records and type unions to group
 parameters together to describe these two conditions.
 
@@ -270,7 +348,7 @@ that accepts `null` (i.e. no value provided), or any value from an enum.
 
 Note how the JavaScript expression uses the value of the exclusive input parameter
 without taking into consideration a `null` value. If you provide a valid value,
-such as “fasta” (one of the values of the enum), your command should execute
+such as “fasta” (one of the values of the enum), your command should be executed
 successfully:
 
 ```{runcmd} cwltool exclusive-parameter-expressions.cwl --file_format fasta
@@ -286,7 +364,7 @@ output field (a `string`), resulting in failure when running your workflow.
 :emphasize-lines: 5-10
 ```
 
-To correct it, you must remember to use an or operator in your JavaScript expression
+To correct it, you must remember to use an **or** operator in your JavaScript expression
 when using exclusive parameters, or any parameter that allows `null`. For example,
 the expression could be changed to `$(inputs.file_format || 'auto')`, to have
 a default value if none was provided in the command line or job input file.
@@ -298,4 +376,3 @@ a default value if none was provided in the command line or job input file.
 % - Several ways of defining inputs/arguments to tools and workflows - https://github.com/common-workflow-language/user_guide/issues/33
 % - Using an input output in another input - https://github.com/common-workflow-language/user_guide/issues/90
 % - How to use linkMerge - https://github.com/common-workflow-language/user_guide/issues/117 (or maybe move to Advanced?)
-% - Secondary files - https://github.com/common-workflow-language/common-workflow-language/issues/270