diff --git a/.buildinfo b/.buildinfo
new file mode 100644
index 00000000..91f7a384
--- /dev/null
+++ b/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 1048e154f92cd5a18d38b03433e027f9
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/.editorconfig b/.editorconfig
deleted file mode 100644
index 1d7d564d..00000000
--- a/.editorconfig
+++ /dev/null
@@ -1,25 +0,0 @@
-root = true
-
-[*]
-charset = utf-8
-insert_final_newline = true
-trim_trailing_whitespace = true
-
-[*.md]
-indent_size = 2
-indent_style = space
-max_line_length = 100 # Please keep this in sync with bin/lesson_check.py!
-
-[*.r]
-max_line_length = 80
-
-[*.py]
-indent_size = 4
-indent_style = space
-max_line_length = 79
-
-[*.sh]
-end_of_line = lf
-
-[Makefile]
-indent_style = tab
diff --git a/.gitignore b/.gitignore
deleted file mode 100644
index 27af20da..00000000
--- a/.gitignore
+++ /dev/null
@@ -1,12 +0,0 @@
-*.pyc
-*~
-.DS_Store
-.ipynb_checkpoints
-.sass-cache
-.jekyll-cache/
-__pycache__
-_site
-.Rproj.user
-.Rhistory
-.RData
-
diff --git a/_episodes/.gitkeep b/.nojekyll
similarity index 100%
rename from _episodes/.gitkeep
rename to .nojekyll
diff --git a/.travis.yml b/.travis.yml
deleted file mode 100644
index 5653b5a5..00000000
--- a/.travis.yml
+++ /dev/null
@@ -1,21 +0,0 @@
-services:
- - docker
-
-language: python
-python:
- - 3.8
-
-cache:
- pip: true
-
-branches:
- only:
- - gh-pages
- - /.*/
-
-before_script:
- - pip install -U pip setuptools wheel typing
- - pip install cwltool cwltest html5lib
-
-script:
- - make RUNNER=cwltool unittest-examples
diff --git a/.zenodo.json b/.zenodo.json
deleted file mode 100644
index 5195b19e..00000000
--- a/.zenodo.json
+++ /dev/null
@@ -1,33 +0,0 @@
-{
- "description": "Common Workflow Language User Guide",
- "license": "CC-BY-4.0",
- "title": "Common Workflow Language User Guide",
- "upload_type": "publication",
- "publication_type": "softwaredocumentation",
- "creators": [
- {
- "affiliation": "European Molecular Biology Laboratory",
- "orcid": "https://orcid.org/0000-0003-1766-456X",
- "name": "Toby Hodges"
- },
- {
- "affiliation": "Common Workflow Language project",
- "orcid": "https://orcid.org/0000-0002-2961-9670",
- "name": "Michael R. Crusoe"
- }
- ],
- "access_right": "open",
- "notes": "Based off of the excellent Software/Data Carpentry templates: https://doi.org/10.5281/zenodo.838778",
- "related_identifiers": [
- {
- "scheme": "url",
- "identifier": "https://github.com/common-workflow-language/user_guide",
- "relation": "isSupplementTo"
- },
- {
- "scheme": "doi",
- "identifier": "10.5281/zenodo.840129",
- "relation": "isPartOf"
- }
- ]
-}
diff --git a/01-introduction/index.md.html b/01-introduction/index.md.html
new file mode 100644
index 00000000..bc7c2f1d
--- /dev/null
+++ b/01-introduction/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/02-1st-example/index.md.html b/02-1st-example/index.md.html
new file mode 100644
index 00000000..bc7c2f1d
--- /dev/null
+++ b/02-1st-example/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/03-input/index.md.html b/03-input/index.md.html
new file mode 100644
index 00000000..9fce93fc
--- /dev/null
+++ b/03-input/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/04-output/index.md.html b/04-output/index.md.html
new file mode 100644
index 00000000..d0715100
--- /dev/null
+++ b/04-output/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/05-stdout/index.md.html b/05-stdout/index.md.html
new file mode 100644
index 00000000..d0715100
--- /dev/null
+++ b/05-stdout/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/06-params/index.md.html b/06-params/index.md.html
new file mode 100644
index 00000000..9a7642c0
--- /dev/null
+++ b/06-params/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/07-containers/index.md.html b/07-containers/index.md.html
new file mode 100644
index 00000000..6a1359ec
--- /dev/null
+++ b/07-containers/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/08-arguments/index.md.html b/08-arguments/index.md.html
new file mode 100644
index 00000000..7009a241
--- /dev/null
+++ b/08-arguments/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/09-array-inputs/index.md.html b/09-array-inputs/index.md.html
new file mode 100644
index 00000000..9fce93fc
--- /dev/null
+++ b/09-array-inputs/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/10-array-outputs/index.md.html b/10-array-outputs/index.md.html
new file mode 100644
index 00000000..d0715100
--- /dev/null
+++ b/10-array-outputs/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/11-records/index.md.html b/11-records/index.md.html
new file mode 100644
index 00000000..9fce93fc
--- /dev/null
+++ b/11-records/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/12-env/index.md.html b/12-env/index.md.html
new file mode 100644
index 00000000..74332c1a
--- /dev/null
+++ b/12-env/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/13-expressions/index.md.html b/13-expressions/index.md.html
new file mode 100644
index 00000000..aaeb3e55
--- /dev/null
+++ b/13-expressions/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/14-runtime/index.md.html b/14-runtime/index.md.html
new file mode 100644
index 00000000..3770abba
--- /dev/null
+++ b/14-runtime/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/15-staging/index.md.html b/15-staging/index.md.html
new file mode 100644
index 00000000..6533cc35
--- /dev/null
+++ b/15-staging/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/16-file-formats/index.md.html b/16-file-formats/index.md.html
new file mode 100644
index 00000000..2c5b7c9f
--- /dev/null
+++ b/16-file-formats/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/17-metadata/index.md.html b/17-metadata/index.md.html
new file mode 100644
index 00000000..9e6250a5
--- /dev/null
+++ b/17-metadata/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/19-custom-types/index.md.html b/19-custom-types/index.md.html
new file mode 100644
index 00000000..96f69a52
--- /dev/null
+++ b/19-custom-types/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/20-software-requirements/index.md.html b/20-software-requirements/index.md.html
new file mode 100644
index 00000000..337d6866
--- /dev/null
+++ b/20-software-requirements/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/21-1st-workflow/index.md.html b/21-1st-workflow/index.md.html
new file mode 100644
index 00000000..b2ac176b
--- /dev/null
+++ b/21-1st-workflow/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/22-nested-workflows/index.md.html b/22-nested-workflows/index.md.html
new file mode 100644
index 00000000..161dc645
--- /dev/null
+++ b/22-nested-workflows/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/23-scatter-workflow/index.md.html b/23-scatter-workflow/index.md.html
new file mode 100644
index 00000000..590450f9
--- /dev/null
+++ b/23-scatter-workflow/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/24_conditional-workflow/index.md.html b/24_conditional-workflow/index.md.html
new file mode 100644
index 00000000..36a45615
--- /dev/null
+++ b/24_conditional-workflow/index.md.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/AUTHORS b/AUTHORS
deleted file mode 100644
index 04e1f5ab..00000000
--- a/AUTHORS
+++ /dev/null
@@ -1 +0,0 @@
-FIXME: list authors' names and email addresses.
\ No newline at end of file
diff --git a/CITATION b/CITATION
deleted file mode 100644
index 6fc87ca8..00000000
--- a/CITATION
+++ /dev/null
@@ -1,34 +0,0 @@
-# Citation
-
-To cite CWL as a project, as a language, or as a standard, use:
-
-Amstutz, Peter; Crusoe, Michael R; Tijanić, Nebojša; Chapman, Brad;
-Chilton, John; Heuer, Michael; Kartashov, Andrey; Kern, John; Leehr, Dan;
-Ménager, Hervé; Nedeljkovich, Maya; Scales, Matt; Soiland-Reyes, Stian;
-Stojanovic, Luka (2016): Common Workflow Language, v1.0. Specification,
-Common Workflow Language working group. https://w3id.org/cwl/v1.0/
-https://dx.doi.org/10.6084/m9.figshare.3115156.v2
-
-@data{cwl,
- doi = {10.6084/m9.figshare.3115156.v2},
- url = {https://doi.org/10.6084/m9.figshare.3115156.v2},
- author = {Peter Amstutz; Michael R. Crusoe; Nebojša Tijanić; Brad Chapman;
-John Chilton; Michael Heuer; Andrey Kartashov; John Kern; Dan Leehr;
-Hervé Ménager; Maya Nedeljkovich; Matt Scales; Stian Soiland-Reyes;
-Luka Stojanovic
- },
- publisher = {Figshare},
- institution = {Common Workflow Language working group},
- title = {Common Workflow Language, v1.0},
- year = {2016}
-}
-
-# the above is from https://github.com/common-workflow-language/common-workflow-language/blob/master/CITATION
-
-Our preferred DOI for the "CWL User Guide" is http://doi.org/10.5281/zenodo.840129
-
-The latest DOI for the "CWL User Guide" is:
-[](https://zenodo.org/badge/latestdoi/89621457)
-
-The structure and style of this user guide is derived from [the Carpentries](https://github.com/carpentries)
-lesson template: [](https://doi.org/10.5281/zenodo.838778)
diff --git a/CODE_OF_CONDUCT.html b/CODE_OF_CONDUCT.html
new file mode 100644
index 00000000..16610abb
--- /dev/null
+++ b/CODE_OF_CONDUCT.html
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
deleted file mode 100644
index c0ac4141..00000000
--- a/CODE_OF_CONDUCT.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-layout: page
-title: "Contributor Code of Conduct"
----
-As contributors and maintainers of this project,
-we pledge to respect all people who contribute through reporting issues,
-posting feature requests,
-updating documentation,
-submitting pull requests or patches,
-and other activities.
-
-The CWL Project is dedicated to providing a harassment-free experience for
-everyone, regardless of gender, gender identity and expression, sexual
-orientation, disability, physical appearance, body size, age, race, or religion.
-We do not tolerate harassment of participants in any form.
-
-This code of conduct applies to all CWL Project spaces, including the Google
-Group, the Gitter chat room, the Google Hangouts chats, both online and off.
-Anyone who violates this code of conduct may be sanctioned or expelled from
-these spaces at the discretion of the leadership team.
-
-For more details, see the [complete CWL project code of conduct](https://github.com/common-workflow-language/common-workflow-language/blob/master/CODE_OF_CONDUCT.md).
-
-{% include links.md %}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
deleted file mode 100644
index fcfbc294..00000000
--- a/CONTRIBUTING.md
+++ /dev/null
@@ -1,148 +0,0 @@
-# Contributing
-
-The [Common Workflow Language project](cwl-site) is an open source project,
-and we welcome contributions of all kinds:
-new lessons,
-fixes to existing material,
-bug reports,
-and reviews of proposed changes are all welcome.
-
-## Contributor Agreement
-
-By contributing,
-you agree that we may redistribute your work under [our license](LICENSE.md).
-In exchange,
-we will address your issues and/or assess your change proposal as promptly as we can,
-and help you become a member of our community.
-Everyone involved in the [Common Workflow Language project](cwl-site)
-agrees to abide by our [code of conduct](CONDUCT.md).
-
-## How to Contribute
-
-The easiest way to get started is to file an issue
-to tell us about a spelling mistake,
-some awkward wording,
-or a factual error.
-This is a good way to introduce yourself
-and to meet some of our community members.
-
-1. If you do not have a [GitHub][github] account,
- you can [send us comments by email][discuss-list].
- However,
- we will be able to respond more quickly if you use one of the other methods described below.
-
-2. If you have a [GitHub][github] account,
- or are willing to [create one][github-join],
- but do not know how to use Git,
- you can report problems or suggest improvements by [creating an issue][issues].
- This allows us to assign the item to someone
- and to respond to it in a threaded discussion.
-
-3. If you are comfortable with Git,
- and would like to add or change material,
- you can submit a pull request (PR).
- Instructions for doing this are [included below](#using-github).
-
-## Where to Contribute
-
-1. If you wish to change this lesson,
- please work in ,
- which can be viewed at .
-
-2. If you wish to change the example lesson,
- please work in ,
- which documents the format of our lessons
- and can be viewed at .
-
-3. If you wish to change the template used for workshop websites,
- please work in .
- The home page of that repository explains how to set up workshop websites,
- while the extra pages in
- provide more background on our design choices.
-
-4. If you wish to change CSS style files, tools,
- or HTML boilerplate for lessons or workshops stored in `_includes` or `_layouts`,
- please work in .
-
-## What to Contribute
-
-There are many ways to contribute,
-from writing new exercises and improving existing ones
-to updating or filling in the documentation
-and submitting [bug reports][issues]
-about things that don't work, aren't clear, or are missing.
-If you are looking for ideas,
-please see [the list of issues for this repository][issues],
-or the issues for [Common Workflow Language](cwl-issues) project itself.
-
-Comments on issues and reviews of pull requests are just as welcome:
-we are smarter together than we are on our own.
-Reviews from novices and newcomers are particularly valuable:
-it's easy for people who have been using these lessons for a while
-to forget how impenetrable some of this material can be,
-so fresh eyes are always welcome.
-
-
-## Using GitHub
-
-If you choose to contribute via GitHub, you may want to look at
-[How to Contribute to an Open Source Project on GitHub][how-contribute].
-To manage changes, we follow [GitHub flow][github-flow].
-Each lesson has two maintainers who review issues and pull requests or encourage others to do so.
-The maintainers are community volunteers and have final say over what gets merged into the lesson.
-To use the web interface for contributing to a lesson:
-
-1. Fork the originating repository to your GitHub profile.
-2. Within your version of the forked repository, move to the `gh-pages` branch and
-create a new branch for each significant change being made.
-3. Navigate to the file(s) you wish to change within the new branches and make revisions as required.
-4. Commit all changed files within the appropriate branches.
-5. Create individual pull requests from each of your changed branches
-to the `gh-pages` branch within the originating repository.
-6. If you receive feedback, make changes using your issue-specific branches of the forked
-repository and the pull requests will update automatically.
-7. Repeat as needed until all feedback has been addressed.
-
-When starting work, please make sure your clone of the originating `gh-pages` branch is up-to-date
-before creating your own revision-specific branch(es) from there.
-Additionally, please only work from your newly-created branch(es) and *not*
-your clone of the originating `gh-pages` branch.
-Lastly, published copies of all the lessons are available in the `gh-pages` branch of the originating
-repository for reference while revising.
-
-## Other Resources
-
-General discussion of [Common Workflow Language](cwl-site) project
-happens on the [discussion mailing list][discuss-list],
-which everyone is welcome to join.
-
-[dc-issues]: https://github.com/issues?q=user%3Adatacarpentry
-[dc-lessons]: http://datacarpentry.org/lessons/
-[dc-site]: http://datacarpentry.org/
-[discuss-list]: https://groups.google.com/forum/#!forum/common-workflow-language
-[github]: https://github.com
-[github-flow]: https://guides.github.com/introduction/flow/
-[github-join]: https://github.com/join
-[how-contribute]: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github
-[issues]: https://github.com/common-workflow-language/user_guide/issues
-[repo]: https://github.com/common-workflow-language/user_guide
-[swc-issues]: https://github.com/issues?q=user%3Aswcarpentry
-[swc-lessons]: https://software-carpentry.org/lessons/
-[swc-site]: https://software-carpentry.org/
-[cwl-site]: https://www.commonwl.org/
diff --git a/Gemfile b/Gemfile
deleted file mode 100644
index 02b7beb2..00000000
--- a/Gemfile
+++ /dev/null
@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
-
-# gem "rails"
-
-gem "jekyll", "~> 4.1"
-
-gem "jekyll-sitemap", "~> 1.4"
diff --git a/Gemfile.lock b/Gemfile.lock
deleted file mode 100644
index 83a7a9f9..00000000
--- a/Gemfile.lock
+++ /dev/null
@@ -1,70 +0,0 @@
-GEM
- remote: https://rubygems.org/
- specs:
- addressable (2.8.0)
- public_suffix (>= 2.0.2, < 5.0)
- colorator (1.1.0)
- concurrent-ruby (1.1.7)
- em-websocket (0.5.2)
- eventmachine (>= 0.12.9)
- http_parser.rb (~> 0.6.0)
- eventmachine (1.2.7)
- ffi (1.13.1)
- forwardable-extended (2.6.0)
- http_parser.rb (0.6.0)
- i18n (1.8.5)
- concurrent-ruby (~> 1.0)
- jekyll (4.1.1)
- addressable (~> 2.4)
- colorator (~> 1.0)
- em-websocket (~> 0.5)
- i18n (~> 1.0)
- jekyll-sass-converter (~> 2.0)
- jekyll-watch (~> 2.0)
- kramdown (~> 2.1)
- kramdown-parser-gfm (~> 1.0)
- liquid (~> 4.0)
- mercenary (~> 0.4.0)
- pathutil (~> 0.9)
- rouge (~> 3.0)
- safe_yaml (~> 1.0)
- terminal-table (~> 1.8)
- jekyll-sass-converter (2.1.0)
- sassc (> 2.0.1, < 3.0)
- jekyll-sitemap (1.4.0)
- jekyll (>= 3.7, < 5.0)
- jekyll-watch (2.2.1)
- listen (~> 3.0)
- kramdown (2.3.1)
- rexml
- kramdown-parser-gfm (1.1.0)
- kramdown (~> 2.0)
- liquid (4.0.3)
- listen (3.3.3)
- rb-fsevent (~> 0.10, >= 0.10.3)
- rb-inotify (~> 0.9, >= 0.9.10)
- mercenary (0.4.0)
- pathutil (0.16.2)
- forwardable-extended (~> 2.6)
- public_suffix (4.0.6)
- rb-fsevent (0.10.4)
- rb-inotify (0.10.1)
- ffi (~> 1.0)
- rexml (3.2.5)
- rouge (3.25.0)
- safe_yaml (1.0.5)
- sassc (2.4.0)
- ffi (~> 1.9)
- terminal-table (1.8.0)
- unicode-display_width (~> 1.1, >= 1.1.1)
- unicode-display_width (1.7.0)
-
-PLATFORMS
- ruby
-
-DEPENDENCIES
- jekyll (~> 4.1)
- jekyll-sitemap (~> 1.4)
-
-BUNDLED WITH
- 2.1.4
diff --git a/LICENSE.html b/LICENSE.html
new file mode 100644
index 00000000..39883424
--- /dev/null
+++ b/LICENSE.html
@@ -0,0 +1,611 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 5. Licenses — Common Workflow Language User Guide 0.1 documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to main content
+
+
+
+
+
+
+
+
+
+
+
+
+
No additional restrictions—You may not apply legal terms or
+technological measures that legally restrict others from doing
+anything the license permits. With the understanding that:
+
+
You do not have to comply with the license for elements of the
+material in the public domain or where your use is permitted by an
+applicable exception or limitation.
+
No warranties are given. The license may not give you all of the
+permissions necessary for your intended use. For example, other
+rights such as publicity, privacy, or moral rights may limit how you
+use the material.
Except where otherwise noted, the example programs and other software
+provided by Common Workflow Language project are made available under the
+OSI-approved
+Apache 2.0 license.
+
Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an “AS IS” BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
-graph TD
- inputs --> example_flag
- example_flag --> type
- type --- bool((boolean))
- example_flag --> inputBinding
- inputBinding --> position
- inputBinding --> prefix
- position --- posval((1))
- prefix --- prefval(('-f'))
-
-
-### Arrays
-
-In certain circumstances it is necessary to provide
-multiple values or objects for a single key.
-As we've already seen in the [Maps](#Maps) section above,
-more than one key-value pair can be mapped to a single key.
-However, it is also possible to define multiple values for a key
-without having to provide a unique key for each value.
-We can achieve this with an _array_,
-where each value is defined on its own line and preceded by `-`.
-For example:
-
-```yaml
-touchfiles:
- - foo.txt
- - bar.dat
- - baz.txt
-```
-
-and a more complex example combining maps and arrays:
-
-```yaml
-exclusive_parameters:
- type:
- - type: record
- name: itemC
- fields:
- itemC:
- type: string
- inputBinding:
- prefix: -C
- - type: record
- name: itemD
- fields:
- itemD:
- type: string
- inputBinding:
- prefix: -D
-```
-
-### JSON Style
-
-YAML is based on [JavaScript Object Notation (JSON)][json]
-and maps and arrays can also be defined in YAML using the native JSON syntax.
-For example:
-
-```yaml
-touchfiles: [foo.txt, bar.dat, baz.txt] # equivalent to first Arrays example
-```
-
-and:
-
-```yaml
-# equivalent to the `inputs` example in "Maps" above
-inputs: {example_flag: {type: boolean, inputBinding: {position: 1, prefix: -f}}}
-```
-
-Native JSON can be useful
-to indicate where a field is being left intentionally empty
-(such as `[]` for an empty array),
-and where it makes more sense
-for the values to be located on the same line
-(such as when providing option flags and their values in a shell command).
-However, as the second example above shows,
-it can severely affect the readability of a YAML file
-and should be used sparingly.
-
-### Reference
-
-The [Learn YAML in Y Minutes][yaml-y-mins] reference was very helpful for us
-while we wrote this guide,
-though it also covers features that are not valid in CWL.
-
-[camelCase]: https://en.wikipedia.org/wiki/Camel_case
-[yaml-y-mins]: https://learnxinyminutes.com/docs/yaml/
-
-{% include links.md %}
diff --git a/_images/CWL-Logo-HD-cropped2.png b/_images/CWL-Logo-HD-cropped2.png
new file mode 100644
index 00000000..f7df48db
Binary files /dev/null and b/_images/CWL-Logo-HD-cropped2.png differ
diff --git a/_images/graphviz-31e64e790986643ef2b3f5e6bc28d3d39838e9be.svg b/_images/graphviz-31e64e790986643ef2b3f5e6bc28d3d39838e9be.svg
new file mode 100644
index 00000000..abe1a9b5
--- /dev/null
+++ b/_images/graphviz-31e64e790986643ef2b3f5e6bc28d3d39838e9be.svg
@@ -0,0 +1,60 @@
+
+
+
+
+
diff --git a/_images/graphviz-39ddc5fddd7e5ad94f50549c8694b6091ea24ae2.svg b/_images/graphviz-39ddc5fddd7e5ad94f50549c8694b6091ea24ae2.svg
new file mode 100644
index 00000000..a89729fd
--- /dev/null
+++ b/_images/graphviz-39ddc5fddd7e5ad94f50549c8694b6091ea24ae2.svg
@@ -0,0 +1,48 @@
+
+
+
+
+
diff --git a/_images/graphviz-4d746944e4b361d70c103c350377e92490136b86.svg b/_images/graphviz-4d746944e4b361d70c103c350377e92490136b86.svg
new file mode 100644
index 00000000..372eb51f
--- /dev/null
+++ b/_images/graphviz-4d746944e4b361d70c103c350377e92490136b86.svg
@@ -0,0 +1,74 @@
+
+
+
+
+
diff --git a/_images/graphviz-50f71480e1fde5bfe7ca5afa005f8614587f43e8.svg b/_images/graphviz-50f71480e1fde5bfe7ca5afa005f8614587f43e8.svg
new file mode 100644
index 00000000..588f0196
--- /dev/null
+++ b/_images/graphviz-50f71480e1fde5bfe7ca5afa005f8614587f43e8.svg
@@ -0,0 +1,48 @@
+
+
+
+
+
diff --git a/_images/graphviz-b2e161069f145124e4da46557a8340e408a06117.svg b/_images/graphviz-b2e161069f145124e4da46557a8340e408a06117.svg
new file mode 100644
index 00000000..16a5422a
--- /dev/null
+++ b/_images/graphviz-b2e161069f145124e4da46557a8340e408a06117.svg
@@ -0,0 +1,125 @@
+
+
+
+
+
diff --git a/_images/graphviz-ff6041f478840e96bfd2c9c585d00a38ab63ef99.svg b/_images/graphviz-ff6041f478840e96bfd2c9c585d00a38ab63ef99.svg
new file mode 100644
index 00000000..a656a399
--- /dev/null
+++ b/_images/graphviz-ff6041f478840e96bfd2c9c585d00a38ab63ef99.svg
@@ -0,0 +1,48 @@
+
+
+
+
+
diff --git a/_includes/aio-script.md b/_includes/aio-script.md
deleted file mode 100644
index a81fbcdd..00000000
--- a/_includes/aio-script.md
+++ /dev/null
@@ -1,50 +0,0 @@
-{% comment %}
-As a maintainer, you don't need to edit this file.
-If you notice that something doesn't work, please
-open an issue: https://github.com/carpentries/styles/issues/new
-{% endcomment %}
-
-{% include manual_episode_order.html %}
-
-
-
-{% comment %} Create an anchor for every episode. {% endcomment %}
-
-{% for lesson_episode in lesson_episodes %}
- {% if site.episode_order %}
- {% assign episode = site.episodes | where: "slug", lesson_episode | first %}
- {% else %}
- {% assign episode = lesson_episode %}
- {% endif %}
-
-{% endfor %}
diff --git a/_includes/all_keypoints.html b/_includes/all_keypoints.html
deleted file mode 100644
index f0abd251..00000000
--- a/_includes/all_keypoints.html
+++ /dev/null
@@ -1,31 +0,0 @@
-{% comment %}
- Display key points of all episodes for reference.
-{% endcomment %}
-
-{% include base_path.html %}
-{% include manual_episode_order.html %}
-
-
diff --git a/_includes/base_path.html b/_includes/base_path.html
deleted file mode 100644
index 7efb3570..00000000
--- a/_includes/base_path.html
+++ /dev/null
@@ -1,27 +0,0 @@
-{% comment %}
-This is adapted from: https://ricostacruz.com/til/relative-paths-in-jekyll
-
-`page.url` gives the URL of the current page with a leading /:
-
-- when the URL ends with the extension (e.g., /foo/bar.html) then we can get
- the depth by counting the number of / and remove - 1
-- when the URL ends with a / (e.g. /foo/bar/) then the number / gives the depth
- directly
-{% endcomment %}
-
-{% assign relative_root_path = '' %}
-
-{% assign last_char = page.url | slice: -1 %}
-
-{% if last_char == "/"}
-{% assign offset = 0 %}
-{% else %}
-{% assign offset = 1 %}
-{% endif %}
-
-{% assign depth = page.url | split: '/' | size | minus: offset %}
-{% if depth <= 1 %}{% assign relative_root_path = '.' %}
-{% elsif depth == 2 %}{% assign relative_root_path = '..' %}
-{% elsif depth == 3 %}{% assign relative_root_path = '../..' %}
-{% elsif depth == 4 %}{% assign relative_root_path = '../../..' %}
-{% endif %}
diff --git a/_includes/carpentries.html b/_includes/carpentries.html
deleted file mode 100644
index c032bd54..00000000
--- a/_includes/carpentries.html
+++ /dev/null
@@ -1,70 +0,0 @@
-{% comment %}
- General description of Software, Data, and Library Carpentry.
-{% endcomment %}
-
-{% include base_path.html %}
-
-
-
-
-
-
-
The Carpentries comprises
- Software Carpentry, Data Carpentry, and Library Carpentry communities of Instructors, Trainers,
- Maintainers, helpers, and supporters who share a mission to teach
- foundational coding and data science skills to researchers and people
- working in library- and information-related roles. In January,
- 2018, The Carpentries was formed by the merger of Software Carpentry and
- Data Carpentry. Library Carpentry became an official Carpentries Lesson Program in November 2018.
-
-
While individual lessons and workshops continue to be run under each
- lesson project, The Carpentries provide overall staffing and governance, as
- well as support for assessment, instructor training and mentoring.
- Memberships are joint, and the Carpentries project maintains a shared Code
- of Conduct. The Carpentries is a fiscally sponsored project of Community
- Initiatives, a registered 501(c)3 non-profit based in California, USA.
-
-
-
-
-
-
-
-
Since 1998, Software Carpentry has
- been teaching researchers across all disciplines the foundational coding
- skills they need to get more done in less time and with less pain. Its
- volunteer instructors have run hundreds of events for thousands of learners
- around the world. Now that all research involves some degree of
- computational work, whether with big data, cloud computing, or simple task
- automation, these skills are needed more than ever.
-
-
-
-
-
-
-
-
-
Data Carpentry develops and teaches
- workshops on the fundamental data skills needed to conduct research. Its
- target audience is researchers who have little to no prior computational
- experience, and its lessons are domain specific, building on learners'
- existing knowledge to enable them to quickly apply skills learned to their
- own research. Data Carpentry workshops take researchers through the entire
- data life cycle.
-
-
-
-
-
-
-
-
-
Library Carpentry develops lessons and
- teaches workshops for and with people working in library- and
- information-related roles. Its goal is to create an on-ramp to empower this
- community to use software and data in their own work, as well as be
- advocates for and train others in efficient, effective and reproducible data
- and software practices.
- Data Carpentry
- aims to help researchers get their work done
- in less time and with less pain
- by teaching them basic research computing skills.
- This hands-on workshop will cover basic concepts and tools,
- including program design, version control, data management,
- and task automation.
- Participants will be encouraged to help one another
- and to apply what they have learned to their own research problems.
-
- Who:
- The course is aimed at graduate students and other researchers.
-
- You don't need to have any previous knowledge of the tools
- that will be presented at the workshop.
-
-
diff --git a/_includes/episode_break.html b/_includes/episode_break.html
deleted file mode 100644
index 36d2d2fa..00000000
--- a/_includes/episode_break.html
+++ /dev/null
@@ -1,15 +0,0 @@
-{% comment %}
- Display a break's timings in a box similar to a learning episode's.
-{% endcomment %}
-
diff --git a/_includes/episode_navbar.html b/_includes/episode_navbar.html
deleted file mode 100644
index 5abf86f2..00000000
--- a/_includes/episode_navbar.html
+++ /dev/null
@@ -1,42 +0,0 @@
-{% comment %}
-For some reason, the relative_root_path seems out of scope in this file, so we
-need to re-assign it here
-{% endcomment %}
-
-{% include base_path.html %}
-
-{% comment %}
- Navigation bar for an episode.
-{% endcomment %}
-
-{% include manual_episode_order.html %}
-{% comment %}
- 'previous_episode' and 'next_episodes' are defined in 'manual_episode_order.html'.
- These replace 'page.previous' and 'page.next' objects, correspondingly.
-{% endcomment %}
-
-
diff --git a/_includes/favicons.html b/_includes/favicons.html
deleted file mode 100644
index 85628d59..00000000
--- a/_includes/favicons.html
+++ /dev/null
@@ -1,36 +0,0 @@
-{% assign favicon_url = relative_root_path | append: '/assets/favicons/' | append: site.carpentry %}
-
-{% if site.carpentry == 'swc' %}
-{% assign carpentry = 'Software Carpentry' %}
-{% elsif site.carpentry == 'dc' %}
-{% assign carpentry = 'Data Carpentry' %}
-{% elsif site.carpentry == 'lc' %}
-{% assign carpentry = 'Library Carpentry' %}
-{% elsif site.carpentry == 'cp' %}
-{% assign carpentry = 'The Carpentries' %}
-{% elsif site.carpentry == 'cwl' %}
-{% assign carpentry = 'The Common Workflow Language Project' %}
-{% endif %}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/_includes/gh_variables.html b/_includes/gh_variables.html
deleted file mode 100644
index 3fdae4ac..00000000
--- a/_includes/gh_variables.html
+++ /dev/null
@@ -1,45 +0,0 @@
-{% comment %}
-When rendering websites locally, `site.github.url` doesn't get resolved properly
-unless a GitHub Personal Access Token is set up and available in the
-environment. This leads to warnings and errors when trying to serve the site
-locally. To work around this, we use the `jekyll.environment` variable which is
-set to `development` when rendering the site locally, and set to `production` on
-GitHub where `site.github.url` is defined.
-{% endcomment %}
-
-{% if jekyll.environment == "production" %}
-
-{% comment %}
-First, get the name of the repository
-{% endcomment %}
-{% assign repo_name = site.github.repository_name %}
-
-{% comment %}
-`site.github.public_repositories` contains comprehensive information for all public repositories for the organization. We use `where` to extract the part
-of the metadata that is relevant to the present repository.
-{% endcomment %}
-{% assign repo_info = site.github.public_repositories | where: "name", repo_name %}
-
-{% comment %}
-Now, we can extract the default branch for the repo
-{% endcomment %}
-{% assign default_branch = repo_info[0].default_branch %}
-
-{% comment %}
-Other variables requested by the template
-{% endcomment %}
-{% assign repo_url = site.github.repository_url %}
-{% assign search_domain_url = site.github.url %}
-{% assign project_title = site.github.project_title %}
-{% assign source_branch = site.github.source.branch %}
-
-{% elsif jekyll.environment == "development" %}
-
-{% assign repo_name = "" %}
-{% assign repo_url = "" %}
-{% assign default_branch = "" %}
-{% assign search_domain_url = "" %}
-{% assign project_title = "" %}
-{% assign source_branch = "" %}
-
-{% endif %}
diff --git a/_includes/javascript.html b/_includes/javascript.html
deleted file mode 100644
index fcc74e6e..00000000
--- a/_includes/javascript.html
+++ /dev/null
@@ -1,14 +0,0 @@
-{% comment %}
- JavaScript used in lesson and workshop pages.
-{% endcomment %}
-
-
-
-
diff --git a/_includes/lc/intro.html b/_includes/lc/intro.html
deleted file mode 100644
index b218f2ba..00000000
--- a/_includes/lc/intro.html
+++ /dev/null
@@ -1,19 +0,0 @@
-
- Library Carpentry
- is made by people working in library- and information-related roles to help you:
-
-
-
automate repetitive, boring, error-prone tasks
-
create, maintain and analyze sustainable and reusable data
-
work effectively with IT and systems colleagues
-
better understand the use of software in research
-
and much more...
-
-
-
- Library Carpentry introduces you to the fundamentals of computing
- and provides you with a platform for further self-directed learning.
- For more information on what we teach and why, please see our paper
- "Library Carpentry: software skills training for library professionals".
-
-
- Who:
- The course is for people working in library- and information-related roles.
-
- You don't need to have any previous knowledge of the tools that
- will be presented at the workshop.
-
-
-
-{% endif %}
diff --git a/_includes/manual_episode_order.html b/_includes/manual_episode_order.html
deleted file mode 100644
index 2928ee85..00000000
--- a/_includes/manual_episode_order.html
+++ /dev/null
@@ -1,111 +0,0 @@
-{% comment %}
- This file enables manual episode ordering until
- GitHub Pages switches to Jekyll that supports it
- without any major hackery. Note, some logic will
- be required even when this transition happens
- but it won't be as involved as what we have to do
- in this file.
-
- To order lesson episodes or extras manually
- (instead of the default alpha-numerical order),
- create array variables 'episode_order' and
- 'extras_order' in `_config.yml` like so:
-
- episode_order:
- - episodeA
- - episodeB
-
- extras_order:
- - extraA
- - extraB
-
- Note that "Reference" page is currently always
- added to "Extras" as the first item.
-
- The main outcomes of the code in this file are:
- - 'lesson_episodes' variable that replaces
- 'site.episodes' variable when manual episode
- order is defined.
- - 'lesson_extras' variable that replaces
- 'site.extras' variable when manual ordering of
- files in '_extras' is used
- - 'previous_episode' and 'next_episode' objects
- that replace 'page.previous' and 'page.next' variables,
- correspondingly, and that have such properties
- as 'url' and 'title' and that are used in
- 'episode_navbar.html'.
-
- When episode order is specified manualy, the 'lesson_episodes'
- variable contains a list of episode names ("slugs", to be precise;
- "slug" is the episode name without '.md'). Therefore, when we
- iterate over 'lesson_episodes' (in syllabus.html and navbar.html) ,
- we have to check whether we use manual episode ordering and, if so,
- find the corresponding episode object. This is what we do with the
- following code in every loop over 'lesson_episodes':
-
- {% if site.episode_order %}
- {% assign episode = site.episodes | where: "slug", lesson_episode | first %}
- {% else %}
- {% assign episode = lesson_episode %}
- {% endif %}
-{% endcomment %}
-
-
-
-{% if site.episode_order %}
- {% assign lesson_episodes = site.episode_order %}
-{% else %}
- {% assign lesson_episodes = site.episodes %}
-{% endif %}
-
-
-{% comment %}
- If 'episode_order' is defined, we need to determine
- - previous episode object ('previous_episode')
- - and next episode object ('next_episode')
-{% endcomment %}
-
-
-{% if site.episode_order %}
- {% for lesson_episode in lesson_episodes %}
-
- {% comment %}
- We iterate over the specified lesson episodes using
- a 'for' loop because we can use
- 'forloop.first', 'forloop.last', and 'forloop.index0'.
- {% endcomment %}
-
- {% unless lesson_episode == page.slug %} {% continue %} {% endunless %}
-
- {% if forloop.first %}
- {% assign previous_episode = nil %}
- {% else %}
- {% assign p_idx = forloop.index0 | minus: 1 %}
- {% assign p_name = lesson_episodes[p_idx] %}
- {% assign previous_episode = site.episodes | where: "slug", p_name | first %}
- {% endif %}
-
- {% if forloop.last == true %}
- {% assign next_episode = nil %}
- {% else %}
- {% assign n_idx = forloop.index0 | plus: 1 %}
- {% assign n_name = lesson_episodes[n_idx] %}
- {% assign next_episode = site.episodes | where: "slug", n_name | first %}
- {% endif %}
- {% endfor %}
-{% else %}
- {% assign previous_episode = page.previous %}
- {% assign next_episode = page.next %}
-{% endif %}
-
-
-
-{% if site.extras_order %}
- {% assign lesson_extras = site.extras_order %}
-{% else %}
- {% assign lesson_extras = site.extras %}
-{% endif %}
-
-{% comment %}
- We do not need to determine "previous" or "next" extra.
-{% endcomment %}
diff --git a/_includes/navbar.html b/_includes/navbar.html
deleted file mode 100644
index 0362851f..00000000
--- a/_includes/navbar.html
+++ /dev/null
@@ -1,120 +0,0 @@
-{% comment %}
- Lesson navigation bar.
-{% endcomment %}
-
-{% include gh_variables.html %}
-{% include manual_episode_order.html %}
-
-
diff --git a/_includes/sc/intro.html b/_includes/sc/intro.html
deleted file mode 100644
index 7b9fbf57..00000000
--- a/_includes/sc/intro.html
+++ /dev/null
@@ -1,18 +0,0 @@
-
- Software Carpentry
- aims to help researchers get their work done
- in less time and with less pain
- by teaching them basic research computing skills.
- This hands-on workshop will cover basic concepts and tools,
- including program design, version control, data management,
- and task automation.
- Participants will be encouraged to help one another
- and to apply what they have learned to their own research problems.
-
- Who:
- The course is aimed at graduate students and other researchers.
-
- You don't need to have any previous knowledge of the tools
- that will be presented at the workshop.
-
-
diff --git a/_includes/syllabus.html b/_includes/syllabus.html
deleted file mode 100644
index 6f113460..00000000
--- a/_includes/syllabus.html
+++ /dev/null
@@ -1,93 +0,0 @@
-{% include base_path.html %}
-
-{% comment %}
- Display syllabus in tabular form.
- Days are displayed if at least one episode has 'start = true'.
-{% endcomment %}
-
-{% include manual_episode_order.html %}
-
-
CWL is a way to describe command-line tools and connect them together to create workflows.
+Because CWL is a specification and not a specific piece of software, tools and workflows
+described using CWL are portable across a variety of platforms that support the CWL standard.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/_includes/workshop_ad.html b/_includes/workshop_ad.html
deleted file mode 100644
index e8e72e34..00000000
--- a/_includes/workshop_ad.html
+++ /dev/null
@@ -1,32 +0,0 @@
-{% comment %}
- Advertising box at the top of a workshop website home page.
-{% endcomment %}
-
-
-
-
{{page.venue}}
-
-
-
{{page.humandate}}
-
{% if page.humantime %}{{page.humantime}}{% endif %}
-
-
-
- Instructors:
- {% if page.instructor %}
- {{page.instructor | join: ', ' %}}
- {% else %}
- to be announced.
- {% endif %}
-
- {% if page.helper %}
-
- Helpers:
- {{page.helper | join: ', ' %}}
-
- {% endif %}
-
-
-
-
-
diff --git a/_includes/workshop_calendar.html b/_includes/workshop_calendar.html
deleted file mode 100644
index f88327dc..00000000
--- a/_includes/workshop_calendar.html
+++ /dev/null
@@ -1 +0,0 @@
-Add to your Google Calendar.
diff --git a/_includes/workshop_footer.html b/_includes/workshop_footer.html
deleted file mode 100644
index 5390ac1d..00000000
--- a/_includes/workshop_footer.html
+++ /dev/null
@@ -1,26 +0,0 @@
-{% comment %}
- Footer for a standard workshop.
-{% endcomment %}
-
diff --git a/_layouts/base.html b/_layouts/base.html
deleted file mode 100644
index 07a49727..00000000
--- a/_layouts/base.html
+++ /dev/null
@@ -1,49 +0,0 @@
----
----
-{% include base_path.html %}
-{% include gh_variables.html %}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- {% include favicons.html %}
-
-
-
-
-
-
- {% if page.title %}{{ page.title }}{% endif %}{% if page.title and site.title %} – {% endif %}{% if site.title %}{{ site.title }}{% endif %}
-
-
-
-
-
- {% include life_cycle.html %}
-
-
- {% include navbar.html %}
-{{ content }}
- {% if site.kind == "workshop" %}
- {% include workshop_footer.html %}
- {% else %}
- {% include lesson_footer.html %}
- {% endif %}
-
- {% include javascript.html %}
-
-
diff --git a/_layouts/break.html b/_layouts/break.html
deleted file mode 100644
index ac582324..00000000
--- a/_layouts/break.html
+++ /dev/null
@@ -1,10 +0,0 @@
----
-layout: base
----
-{% include episode_navbar.html episode_navbar_title=true %}
-
-{% include episode_title.html %}
-{% include episode_break.html %}
-{{content}}
-
-{% include episode_navbar.html episode_navbar_title=false %}
diff --git a/_layouts/episode.html b/_layouts/episode.html
deleted file mode 100644
index 0b276e77..00000000
--- a/_layouts/episode.html
+++ /dev/null
@@ -1,11 +0,0 @@
----
-layout: base
----
-{% include episode_navbar.html episode_navbar_title=true %}
-
-{% include episode_title.html %}
-{% include episode_overview.html %}
-{{content}}
-{% include episode_keypoints.html %}
-
-{% include episode_navbar.html episode_navbar_title=false %}
diff --git a/_layouts/lesson.html b/_layouts/lesson.html
deleted file mode 100644
index f3f7300e..00000000
--- a/_layouts/lesson.html
+++ /dev/null
@@ -1,8 +0,0 @@
----
-layout: base
----
-{% include main_title.html %}
-
- {{ content }}
-
-{% include syllabus.html %}
diff --git a/_layouts/page.html b/_layouts/page.html
deleted file mode 100644
index 656edfef..00000000
--- a/_layouts/page.html
+++ /dev/null
@@ -1,7 +0,0 @@
----
-layout: base
----
-{% include main_title.html %}
-
-{{content}}
-
diff --git a/_layouts/reference.html b/_layouts/reference.html
deleted file mode 100644
index 27c96955..00000000
--- a/_layouts/reference.html
+++ /dev/null
@@ -1,6 +0,0 @@
----
-layout: page
-title: "Reference"
----
-{% include all_keypoints.html %}
-{{content}}
diff --git a/_layouts/workshop.html b/_layouts/workshop.html
deleted file mode 100644
index cf57cdf4..00000000
--- a/_layouts/workshop.html
+++ /dev/null
@@ -1,55 +0,0 @@
----
----
-{% include base_path.html %}
-{% include gh_variables.html %}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- {% if page.redirect %}
-
- {% endif %}
-
-
-
-
-
-
-
-
-
-
- {% include favicons.html %}
-
-
-
-
- {{ page.venue }}: {{ page.humandate }}
-
-
-
- {% include navbar.html %}
- {% include workshop_ad.html %}
-{{ content }}
- {% include workshop_footer.html %}
-
- {% include javascript.html %}
-
-
diff --git a/_sources/LICENSE.md.txt b/_sources/LICENSE.md.txt
new file mode 100644
index 00000000..84798e58
--- /dev/null
+++ b/_sources/LICENSE.md.txt
@@ -0,0 +1,2 @@
+```{include} ../LICENSE.md
+```
diff --git a/_sources/_includes/what-is-cwl.md.txt b/_sources/_includes/what-is-cwl.md.txt
new file mode 100644
index 00000000..f9357b8f
--- /dev/null
+++ b/_sources/_includes/what-is-cwl.md.txt
@@ -0,0 +1,3 @@
+CWL is a way to describe command-line tools and connect them together to create workflows.
+Because CWL is a specification and not a specific piece of software, tools and workflows
+described using CWL are portable across a variety of platforms that support the CWL standard.
diff --git a/_sources/episodes.md.txt b/_sources/episodes.md.txt
new file mode 100644
index 00000000..8057f43b
--- /dev/null
+++ b/_sources/episodes.md.txt
@@ -0,0 +1,12 @@
+---
+orphan: true
+---
+
+# This page has moved
+
+```{attention}
+
+This page is out-of-date and was kept here to preserve the links of the old
+User Guide. Please use the new [Table of Contents](index.md#table-of-contents)
+to browse the User Guide.
+```
diff --git a/_sources/faq.md.txt b/_sources/faq.md.txt
new file mode 100644
index 00000000..7f57e574
--- /dev/null
+++ b/_sources/faq.md.txt
@@ -0,0 +1,458 @@
+# FAQ
+
+% The items here do not look like questions, because we merged the
+% How-Tos with the FAQ. We can/need to change it later.
+
+```{contents}
+:local:
+:backlinks: "top"
+```
+
+## How do I create non "`File`" types using `evalFrom`?
+
+```yaml
+cwlVersion: v1.0 # or v1.1
+class: CommandLineTool
+requirements:
+ InlineJavascriptRequirement: {}
+
+baseCommand: [ echo, "42" ]
+
+inputs: []
+
+stdout: my_number.txt
+
+outputs:
+ my_number:
+ type: int
+ outputBinding:
+ glob: my_number.txt
+ loadContents: True
+ outputEval: $(parselnt(self[0].contents))
+
+ my_number_as_string:
+ type: string
+ outputBinding:
+ glob: my_number.txt
+ loadContents: True
+ outputEval: $(self[0].contents)
+```
+
+## How do I rename an input file?
+
+This example demonstrates how to change the name of an input file
+as part of a tool description.
+This could be useful when you are taking files produced from another
+step in a workflow, and don't want to work with the default names that these
+files were given when they were created.
+
+```yaml
+requirements:
+ InitialWorkDirRequirement:
+ listing:
+ - entry: $(inputs.src1)
+ entryName: newName
+ - entry: $(inputs.src2)
+ entryName: $(inputs.src1.basename)_custom_extension
+```
+
+## How do I rename an output file?
+
+This example demonstrates how to change the name of an output file
+from the default name given to it by a tool:
+
+```yaml
+cwlVersion: v1.0
+class: CommandLineTool
+requirements:
+ InlineJavascriptRequirement: {}
+
+baseCommand: [ touch, otu_table.txt ]
+
+inputs:
+ otu_table_name: string
+
+outputs:
+ otu_table:
+ type: File
+ outputBinding:
+ glob: otu_table.txt
+ outputEval: ${self[0].basename=inputs.otu_table_name; return self;}
+```
+
+By modifying the `basename` field in the `outputEval` field, CWL workflow engines will rename
+the file using the new name for subsequent steps or as a workflow-level output.
+
+## How do I reference a local script?
+
+There are two ways to reference a local script:
+
+The first method involves adding the path to a folder containing your scripts to the `PATH` environment variable. This
+allows you to execute the shell script directly (without explicitly using the `sh` or `bash` commands).
+
+Start with adding a _shebang_ at the top of your file:
+
+```{code-block}
+#!/bin/bash
+```
+
+After that, make the script executable with the command `chmod +x scriptname.sh`
+
+Finally, modify your `PATH` to add the directory where your script is located.
+(It is good practice to use `$HOME/bin` for storing your own scripts).
+
+```bash
+export PATH=$PATH:$HOME/bin
+```
+
+Now you can use `baseCommand: scriptname.sh` to run the script directly.
+
+```cwl
+#!/bin/bash
+cwlVersion: v1.0
+class: CommandLineTool
+baseCommand: scriptname.sh
+```
+
+When you wish to share your work later, you can place your script in a software container in the Docker format.
+
+The second method involves including an input of `type: File` in the script itself:
+
+```cwl
+class: CommandLineTool
+
+inputs:
+ my_script:
+ type: File
+ inputBinding:
+ position: 0
+
+
+ # other inputs go here
+
+baseCommand: sh
+
+outputs: []
+```
+
+## How can I set `self`-based input bindings for optional inputs?
+
+Currently, `cwltool` can't cope with missing optional inputs if their
+input binding makes use of `self`.
+Below is an example workaround for this,
+pending a more sophisticated fix.
+
+```yaml
+#!/usr/bin/env cwl-runner
+cwlVersion: v1.0
+class: CommandLineTool
+
+requirements: { InlineJavascriptRequirement: {} }
+
+inputs:
+ cfg:
+ type: File?
+ inputBinding:
+ prefix: -cfg
+ valueFrom: |
+ ${ if(self === null) { return null;} else { return self.basename; } }
+
+baseCommand: echo
+
+outputs: []
+```
+
+## How can I model a "one-or-the-other" parameter?
+
+Below is an example showing how
+to specify different strings to be added to a command line,
+based on the value given to a Boolean parameter.
+
+```yaml
+cwlVersion: v1.0
+class: CommandLineTool
+requirements:
+ InlineJavascriptRequirement: {}
+inputs:
+ fancy_bool:
+ type: boolean
+ default: false # or true
+ inputBinding:
+ valueFrom: ${if (self) { return "foo";} else { return "bar";}}
+
+baseCommand: echo
+
+outputs: []
+```
+
+## How do I connect a solo value to an input that expects an array of that type?
+
+Add a [`MultipleInputFeatureRequirement`](https://www.commonwl.org/v1.0/Workflow.html#MultipleInputFeatureRequirement)
+along with
+[`linkMerge: merge_nested`](https://www.commonwl.org/v1.0/Workflow.html#WorkflowStepInput):
+
+> merge_nested
+>
+> The input must be an array consisting of exactly one entry for each input link.
+> If "merge_nested" is specified with a single link, the value from the link must be wrapped in a single-item list.
+
+Which means "create a list with exactly these sources as elements".
+
+Or in other words: if the destination is of type `File[]` (an array of `File`s)
+and the source is a single `File` then add `MultipleInputFeatureRequirement` to the Workflow level `requirements`
+and add `linkMerge: merge_nested` under the appropriate `in` entry of the destination step.
+
+```yaml
+cwlVersion: v1.0
+class: Workflow
+
+requirements:
+ MultipleInputFeatureRequirement: {}
+
+inputs:
+ readme: File
+
+steps:
+ first:
+ run: tests/checker_wf/cat.cwl
+ in:
+ cat_in: # type is File[]
+ source: [ readme ] # but the source is of type File
+ linkMerge: merge_nested
+ out: [txt]
+
+outputs:
+ result:
+ type: File
+ outputSource: first/txt
+```
+## How do make an input optional? 💯
+
+To make an input parameter optional, add a question mark to the type declaration.
+
+```yaml
+inputs:
+ InputRead1:
+ type: File
+ inputBinding:
+ position: 100
+
+ #Optional Inputs
+ isCasava:
+ type: boolean?
+ inputBinding:
+ position: 1
+ prefix: "--casava"
+```
+
+## How do I specify an input that must come from a list of predefined values (i.e. How do I use enum inputs) ?
+
+For command line flags that require a specific input as the argument an enum type can be declared in CWL. **Specifying null here is known as long form style. It does the same thing as the question mark on the other inputs.**
+
+```yaml
+Format:
+ type:
+ - "null"
+ - type: enum
+ symbols:
+ - bam
+ - sam
+ - bam_mapped
+ - sam_mapped
+ - fastq
+ inputBinding:
+ position: 2
+ prefix: "--format"
+```
+
+## How do I describe dependent or exclusive input parameters(e.g. How do I use record inputs)?
+
+For commandline flags that are either **mutually exclusive** or **dependent** a special record type can be defined. You can also specify null here to create optional inputs.
+
+```yaml
+#Using record inputs to create mutually exclusive inputs
+
+ Strand:
+ type:
+ - "null"
+ - type: record
+ name: forward
+ fields:
+ forward:
+ type: boolean
+ inputBinding:
+ prefix: "--fr-stranded"
+
+ - type: record
+ name: reverse
+ fields:
+ reverse:
+ type: boolean
+ inputBinding:
+ prefix: "--rf-stranded"
+
+ PseudoBam:
+ type: boolean?
+ inputBinding:
+ prefix: "--pseudobam"
+
+#Using record inputs to create dependent inputs
+
+ GenomeBam:
+ type:
+ - "null"
+ - type: record
+ name: genome_bam
+ fields:
+ genomebam:
+ type: boolean
+ inputBinding:
+ prefix: "--genomebam"
+
+ gtf:
+ type: File
+ inputBinding:
+ prefix: "--gtf"
+
+ chromosomes:
+ type: File
+ inputBinding:
+ prefix: "--chromosomes"
+```
+## How do I set mutually exclusive parameters?
+
+To properly set fields in a record input type, you need to pass a dictionary to the input to properly set the parameters. This is done by using inline JavaScript and returning the dictionary with the key of the field you want to set. The source field is set to indicate the input from the workflow to be used as the value.
+
+```yaml
+steps:
+
+ build_hisat2_index:
+ run: ../Tools/Hisat2-Index.cwl
+ in:
+ InputFiles:
+ source: FastaFiles
+ valueFrom : |
+ ${return {"fasta": self};}
+
+ IndexName: IndexName
+
+ out: [indexes]
+```
+
+## How can I set Booleans?
+
+These can be set by using the default field
+```yaml
+input:
+ default: true
+```
+## What should I do when concatenating strings in inputs?
+
+The valueFrom field must be used instead of default.
+
+```yaml
+input:
+ valueFrom: |
+ My String: $(input.stringvalue)
+```
+
+## I get `cwltool` errors due to filenames with space characters inside. What should I do?
+
+`cwltool` does not allow some characters in filenames by default.
+
+For example, the filename `a space is here.txt` includes 3 space characters.
+
+```console
+ERROR Workflow error, try again with --debug for more information:
+
+Invalid filename: 'a space is here.txt' contains illegal characters
+```
+
+If you can not avoid these dangerous characters, then pass `--relax-path-checks` to `cwltool`.
+
+## What should I do when I get CWL Parameter Reference error due to hyphen in an input identifier?
+
+If `cwltool --validate` returns valid
+
+```console
+$ cwltool --validate cwl/qiime.cwl
+INFO /usr/local/bin/cwltool 1.0.20190831161204
+INFO Resolved 'cwl/qiime.cwl' to 'file:///workspace/cwl/qiime.cwl'
+cwl/qiime.cwl is valid CWL.
+```
+
+But executing it causes an error like:
+
+```console
+$ cwltool cwl/qiime.cwl --sample-input metadata.tsv
+INFO /usr/local/bin/cwltool 1.0.20190831161204
+INFO Resolved 'cwl/qiime.cwl' to 'file:///workspace/cwl/qiime.cwl'
+ERROR Workflow error, try again with --debug for more information:
+cwl/qiime.cwl:14:5: Expression evaluation error:
+ Syntax error in parameter reference '(inputs.sample-input)'. This could be due
+ to using Javascript code without specifying InlineJavascriptRequirement.
+```
+
+The file is here
+
+```cwl
+cwlVersion: v1.0
+class: CommandLineTool
+baseCommand: [qiime, metadata, tabulate]
+arguments:
+ - prefix: --m-input-file
+ valueFrom: $(inputs.sample-input)
+inputs:
+ sample-input: File
+outputs: []
+```
+
+Problem caused by `-` (hyphen character).
+
+```cwl
+valueFrom: $(inputs.sample-input)
+ # ^ this is problem
+...
+
+inputs:
+ sample-input: File
+ # ^ this is problem
+```
+
+
+To fix this error, change `-` (hyphen) to `_` (underscore):
+
+```cwl
+valueFrom: $(inputs.sample_input)
+ # ^ changed here
+
+...
+
+inputs:
+ sample_input: File
+ # ^ changed here
+```
+
+If it is not possible to change the input identifier, then you can use an alternative CWL Parameter Reference syntax:
+
+```cwl
+valueFrom: $(inputs["sample-input"])
+```
+
+## How do I use CWL and cwltool with Singularity?
+
+
+The CWL standards are built around (optional) Docker format containers.
+The reference runner and several other CWL implementations support running
+those Docker format containers using the Singularity engine. Directly
+specifying a Singularity format container is not part of the CWL standards.
+
+## How do I debug the JavaScript in my CWL tool?
+
+You can use the --js-console option of cwltool, or you can try
+creating a JavaScript or TypeScript project for your code, and load it
+using expressionLib, e.g.:
+https://github.com/common-workflow-language/common-workflow-language/blob/master/v1.0/v1.0/template-tool.cwl#L6-L8
+
+% - https://github.com/common-workflow-language/user_guide/issues/6
+% - Maybe adapt some of these (or move to a workaround?) https://www.synapse.org/#!Synapse:syn2813589/wiki/401464
diff --git a/_sources/index.md.txt b/_sources/index.md.txt
new file mode 100644
index 00000000..8e10fa54
--- /dev/null
+++ b/_sources/index.md.txt
@@ -0,0 +1,41 @@
+# Common Workflow Language User Guide
+
+This guide will introduce you to writing workflows using the
+[Common Workflow Language](https://www.commonwl.org/) (CWL)
+open standards. This guide describes the latest specification {{ cwl_version }}.
+
+```{admonition} Contributions and Feedback are Welcome!
+
+If you find that something is missing from this guide, or if you would
+like to provide other feedback, file an Issue on the [project repository
+for this guide][repo]. You can also suggest changes directly in a Pull
+Request by clicking the "Edit this page" button at the right sidebar of
+each page.
+```
+
+## Navigating the User Guide
+
+If you are a beginner user get started with the [Introduction](/introduction/index.md)
+section. For advanced users the subsections of the
+[Topics](/topics/index.md) have detailed information about the
+most common topics for CWL.
+
+The Table of Contents is displayed at the top menu and also on the left sidebar.
+It also appears further down this page but with links to subsections. The right
+sidebar contains links to the sections of each page, and the Search form is on
+the left sidebar.
+
+## Table of Contents
+
+```{toctree}
+:maxdepth: 3
+:numbered:
+
+introduction/index.md
+topics/index.md
+tutorials.md
+faq.md
+LICENSE.md
+```
+
+[repo]: https://github.com/common-workflow-language/user_guide/issues
diff --git a/_sources/introduction/basic-concepts.md.txt b/_sources/introduction/basic-concepts.md.txt
new file mode 100644
index 00000000..c6013a29
--- /dev/null
+++ b/_sources/introduction/basic-concepts.md.txt
@@ -0,0 +1,186 @@
+# Basic Concepts
+
+This section describes the basic concepts for users to get started on working with
+Common Workflow Language (CWL) workflows. Readers are expected to be familiar
+with workflow managers, YAML, and comfortable with following instructions for the
+command-line. The other sections of the user guide cover the same concepts, but
+in more detail. If you are already familiar with CWL or you are looking for more advanced
+content, you may want to skip this section.
+
+## The CWL Specification
+
+```{include} /_includes/what-is-cwl.md
+```
+
+```{image} /_static/images/logos/cwl/CWL-Logo-HD-cropped2.png
+:name: cwl-logo
+:width: 300px
+:align: center
+```
+
+The CWL specification is a document written and maintained by the CWL community.
+The specification has different versions. The version covered in this user guide
+is the {{ cwl_version }}.
+
+The specification version can have up to three numbers separated by `.`s (dots).
+The first number is the major release, used for backward-incompatible changes like
+the removal of deprecated features. The second number is the minor release,
+used for new features or smaller changes that are backward-compatible. The last number
+is used for bug fixes, like typos and other corrections to the specification.
+
+```{note}
+
+The model used for the specification version is called Semantic Versioning. See
+the end of this section to [learn more](#learn-more) about it.
+```
+
+## Implementations
+
+An implementation of the CWL specification is any software written following
+what is defined in a version of the specification document. However, implementations may
+not implement every aspect of the specification. CWL implementations are
+licensed under both Open Source and commercial licenses.
+
+CWL is well suited for describing large-scale workflows in cluster,
+cloud and high performance computing environments where tasks are scheduled
+in parallel across many nodes.
+
+% TODO: add a link to the Core Concepts -> Requirements section below?
+
+
+```{graphviz}
+:name: specification-and-implementations-graph
+:caption: CWL specification, implementations, and other tools.
+:align: center
+
+digraph G {
+ compound=true;
+ rankdir="LR";
+ ranksep=0.75;
+ fontname="Verdana";
+ fontsize="10";
+ graph [splines=ortho];
+ node [fontname="Verdana", fontsize="10", shape=box];
+ edge [fontname="Verdana", fontsize="10"];
+ subgraph cluster_0 {
+ label="Implementations";
+ ranksep=0.25;
+
+ cwltool;
+ toil;
+ Arvados;
+ runner_others[label="..."];
+ label="CWL Runners";
+ }
+
+ subgraph cluster_1 {
+ label="Tools";
+ ranksep=0.25;
+
+ subgraph cluster_2 {
+ "vscode-cwl";
+ "vim-cwl";
+ benten;
+ editor_others[label="..."];
+ label="Editors";
+ }
+
+ subgraph cluster_3 {
+ "CWL Viewer";
+ "vue-cwl";
+ viewer_others[label="..."];
+ label="Viewers";
+ }
+
+ "And more";
+ }
+ cwltool -> "CWL Specification" [ltail=cluster_0, dir=back];
+ "CWL Specification" -> "vscode-cwl" [lhead=cluster_1];
+ "vscode-cwl" -> "CWL Viewer" [style=invis];
+ "CWL Viewer" -> "And more" [style=invis];
+}
+
+```
+
+## Processes and Requirements
+
+A process is a computing unit that takes inputs and produces outputs. The
+behavior of a process can be affected by the inputs, requirements, and hints.
+There are four types of processes defined in the CWL specification
+{{ cwl_version }}:
+
+- A command-line tool.
+- An expression tool.
+- An operation.
+- A workflow.
+
+{{ CWL_PROCESSING_UNITS_GRAPH }}
+
+A command-line tool is a wrapper for a command-line utility like `echo`,
+`ls`, and `tar`. A command-line tool can be called from a workflow.
+
+An expression tool is a wrapper for a JavaScript expression. It can
+be used to simplify workflows and command-line tools, moving common
+parts of a workflow execution into reusable JavaScript code that
+takes inputs and produces outputs like a command-line tool.
+
+Operation is an abstract process that also takes inputs, produces
+outputs, and can be used in a workflow. But it is a special operation
+not so commonly used. It is discussed in the [Operations section](../topics/operations.md) of this user guide.
+
+The workflow is a process that contains steps. Steps can be other
+workflows (nested workflows), command-line tools, or expression tools.
+The inputs of a workflow can be passed to any of its steps, while
+the outputs produced by its steps can be used in the final output
+of the workflow.
+
+The CWL specification allows for implementations to provide extra
+functionality and specify prerequisites to workflows through *requirements*.
+There are many requirements defined in the CWL specification, for instance:
+
+- [`InlineJavascriptRequirement`](https://w3id.org/cwl/Workflow.html#InlineJavascriptRequirement) - enables JavaScript in expressions.
+- [`SubworkflowFeatureRequirement`](https://w3id.org/cwl/Workflow.html#SubworkflowFeatureRequirement) - enables nested workflows.
+- [`InitialWorkDirRequirement`](https://w3id.org/cwl/Workflow.html#InitialWorkDirRequirement) - controls staging files in the input directory.
+
+Some CWL runners may provide requirements that are not in the specification.
+For example, GPU requirements are supported in `cwltool` through the
+`cwltool:CUDARequirement` requirement, but it is not part of the
+{{ cwl_version }} specification and may not be supported by other CWL
+runners.
+
+Hints are similar to requirements, but while requirements list features
+that are required, hints list optional features. Requirements are explained
+in detail in the [Requirements](../topics/requirements-and-hints.md) section.
+
+## FAIR Workflows
+
+> The FAIR principles have laid a foundation for sharing and publishing
+> digital assets, and in particular, data. The FAIR principles emphasize
+> machine accessibility and that all digital assets should be Findable,
+> Accessible, Interoperable, and Reusable. Workflows encode the methods
+> by which the scientific process is conducted and via which data are
+> created. It is thus important that workflows both support the creation
+> of FAIR data and themselves adhere to the FAIR principles.
+> — [FAIR Computational Workflows](https://workflows.community/groups/fair/),
+> Workflows Community Initiative.
+
+CWL has roots in "make" and many similar tools that determine order of
+execution, based on dependencies between tasks. However, unlike "make", CWL
+tasks are isolated, and you must be explicit about your inputs and outputs.
+
+The benefit of explicitness and isolation are flexibility, portability, and
+scalability; tools and workflows described with CWL can transparently leverage
+technologies such as Docker and be used with CWL implementations from different
+vendors.
+
+`cwltool` also uses the PROV-O standard ontology for data provenance.
+
+## Learn More
+
+- Semantic Versioning -
+- The CWL Specification page in the CWL website:
+- The Command Line Tool Description Standard:
+- The current CWL specification on GitHub: {{ ''.format(cwl_version_text) }}
+- The list of Implementations in the CWL website:
+- PROV-O: The PROV Ontology -
+- CWL Operations are covered in the [Operations](../topics/operations.md) section of this user guide.
diff --git a/_sources/introduction/index.md.txt b/_sources/introduction/index.md.txt
new file mode 100644
index 00000000..78d32ad3
--- /dev/null
+++ b/_sources/introduction/index.md.txt
@@ -0,0 +1,14 @@
+# Introduction
+
+This section will guide you through a short introduction to CWL,
+the prerequisites for following this user guide, and some
+basic concepts that are useful to know before reading the rest of the
+user guide.
+
+```{toctree}
+:maxdepth: 2
+
+quick-start.md
+prerequisites.md
+basic-concepts.md
+```
diff --git a/_sources/introduction/prerequisites.md.txt b/_sources/introduction/prerequisites.md.txt
new file mode 100644
index 00000000..1dc47954
--- /dev/null
+++ b/_sources/introduction/prerequisites.md.txt
@@ -0,0 +1,186 @@
+# Prerequisites
+
+% This page supersedes the old setup page: setup.md. We used that page as a reference while
+% writing this documentation.
+
+The software and configurations listed in this section are prerequisites for
+following this user guide. The CWL standards are implemented by many different
+workflow runners and platforms. This list of requirements focuses on the CWL reference runner,
+`cwltool`. You can use another CWL-compatible runner or workflow system, but the results and
+interface may look different (though the exact workflow outputs should be identical).
+
+```{admonition} CWL Implementations
+
+There are many implementations of the CWL standards. Some are complete CWL runners, while
+others could be plug-ins or extensions to workflow engines. We have a better
+explanation in the [Implementations](basic-concepts.md#implementations) section.
+```
+
+## Operating System
+
+We recommend using an up-to-date operating system. You can choose any
+of the following options for your operating system:
+
+- Linux
+- macOS
+- Windows
+
+```{note}
+If you are using Windows, you will have to install the Windows Subsystem for Linux 2 as documented in the
+[`cwltool` documentation for Microsoft Windows users](https://github.com/common-workflow-language/cwltool/blob/main/README.rst#ms-windows-users).
+Your operating system also needs internet access and a recent version of Python (3.6+).
+```
+
+## CWL Runner
+
+% https://github.com/common-workflow-language/user_guide/issues/166
+% https://www.synapse.org/#!Synapse:syn2813589/wiki/401462
+
+The first thing you will need for running CWL workflows is a CWL runner.
+`cwltool` is a Python Open Source project maintained by the CWL community. It
+is also the CWL reference runner, which means it must support everything in the
+current CWL specification, {{ cwl_version }}.
+
+`cwltool` can be installed with `pip`, `apt`, or `conda`. We recommend using a virtual environment
+like `venv` or `conda`.
+
+```{note}
+Visit the `cwltool` [documentation](https://cwltool.readthedocs.io/en/latest/#install)
+for details on installing `cwltool`.
+```
+
+Let's use a simple CWL tool description `true.cwl` with `cwltool`.
+
+```{literalinclude} /_includes/cwl/true.cwl
+:language: yaml
+:caption: "`true.cwl`"
+:name: true.cwl
+```
+
+The `cwltool` command has an option to validate CWL tool and workflow descriptions. This option will parse the
+CWL document, look for syntax errors, and verify that the workflow descriptions are compliant
+with the CWL standards. However, these actions will be performed without running the document. To validate CWL workflows (or even a
+standalone command line tool description like the above) pass the `--validate` option
+to the `cwltool` command:
+
+```{runcmd} cwltool --validate true.cwl
+:name: validating-truecwl-with-cwltool
+:caption: Validating `true.cwl` with `cwltool`.
+```
+
+You can run the CWL tool description by omitting the `--validate` option:
+
+```{runcmd} cwltool true.cwl
+:name: running-true.cwl-with-cwltool
+:caption: Running `true.cwl` with `cwltool`.
+```
+
+### Generic ``cwl-runner`` alias
+
+`cwl-runner` is an implementation-agnostic alias for any CWL compliant runner. This simply means
+that the `cwl-runner` alias command can be invoked independently, and is not reliant on a particular
+CWL runner program name.
+Users can invoke `cwl-runner` instead of invoking a CWL runner like `cwltool`
+directly. The `cwl-runner` is installed by a system administrator or user to point to the preferred
+CWL implementation.
+This is convenient for environments with multiple CWL runners.
+
+The CWL community publishes a Python package with the name `cwlref-runner` that installs
+an alias for `cwltool` under the name `cwl-runner`.
+
+```{code-block} console
+:name: installing-cwlrunner-with-pip
+:caption: Installing `cwl-runner` alias for cwltool with `pip`.
+
+$ pip install cwlref-runner
+```
+
+Now you can validate and run your workflow with the `cwl-runner` executable,
+which will invoke `cwltool`. You should have the same results and output
+as in the previous section.
+
+```{runcmd} cwl-runner --validate true.cwl
+:name: validating-true.cwl-with-cwl-runner
+:caption: Validating `true.cwl` with `cwl-runner`.
+```
+
+```{runcmd} cwl-runner true.cwl
+:name: running-true.cwl-with-cwl-runner
+:caption: Running `true.cwl` with `cwl-runner`.
+```
+
+Another way to execute `cwl-runner` is by invoking the file directly. For that,
+the first thing you need to do is copy `true.cwl` workflow into a new file:
+`true_shebang.cwl`, and include a special first line, a *shebang*:
+
+```{literalinclude} /_includes/cwl/true_shebang.cwl
+:language: cwl
+:name: "true_shebang.cwl"
+:caption: "`true_shebang.cwl`"
+```
+
+Now you can make the file `true_shebang.cwl` executable with `chmod u+x`.
+
+```{code-block} console
+:name: making-true.cwl-executable
+:caption: Making `true.cwl` executable.
+
+$ chmod u+x true.cwl
+```
+
+And finally, you can execute it directly in the command-line. On execution, the program
+specified in the shebang (`cwl-runner`) will be used to execute the
+rest of the file.
+
+```{runcmd} ./true_shebang.cwl
+:name: running-true_shebang.cwl-with-a-shebang
+:caption: Running `true_shebang.cwl` with a shebang.
+```
+
+```{note}
+The *shebang* is the two-character sequence `#!` at the beginning of a
+script. When the script is executable, the operating system will execute
+the script using the executable specified after the shebang. It is
+considered a good practice to use `/usr/bin/env [executable]` rather than using a hard-coded location, since `/usr/bin/env [executable]`
+looks for the `[executable]` program in the system `PATH`,
+```
+
+## Text Editor
+
+You can use any text editor with CWL, but for syntax highlighting we recommend
+an editor with YAML support. Popular editors are Visual Studio Code, Sublime,
+WebStorm, vim/neovim, and Emacs.
+
+There are extensions for Visual Studio Code and WebStorm that provide
+integration with CWL, and features such as customized syntax highlighting and better
+auto-complete:
+
+- Visual Studio Code with the Benten (CWL) plugin -
+- cwl-plugin for IntelliJ -
+
+The CWL community also maintains a list of editors and viewers:
+
+
+## Docker
+
+% https://github.com/common-workflow-language/user_guide/issues/119
+
+`cwltool` uses Docker to run tools, workflows, and workflow steps that specify a software container.
+Follow the instructions in the Docker documentation to install it for your
+operating system: .
+
+You do not need to know how to write and build Docker containers. In the
+rest of the user guide, we will use existing Docker images for running
+examples, and to clarify the differences between the execution models
+with and without containers.
+
+```{note}
+`cwltool` supports running containers with Docker, Podman, udocker, and
+Singularity. You can also use alternative container registries for pulling
+images.
+```
+
+## Learn More
+
+- The [Implementations](basic-concepts.md#implementations) topic in the next section, Basic Concepts.
+- The Python `venv` module:
diff --git a/_sources/introduction/quick-start.md.txt b/_sources/introduction/quick-start.md.txt
new file mode 100644
index 00000000..0e18127b
--- /dev/null
+++ b/_sources/introduction/quick-start.md.txt
@@ -0,0 +1,107 @@
+# Quick Start
+
+This section will show you a brief overview of what CWL is, and where you
+can learn more about it. No previous knowledge of CWL is required, but you
+must be comfortable following instructions for the command-line.
+
+## “Hello World”
+
+```{include} /_includes/what-is-cwl.md
+```
+
+CWL documents are written in [YAML](../topics/index.md) (and/or JSON).
+The example below shows a simple CWL “Hello World” workflow annotated
+with comments. Note that comments start with `#`:
+
+```{literalinclude} /_includes/cwl/hello_world.cwl
+:language: cwl
+:name: hello_world.cwl
+:caption: "`hello_world.cwl`"
+```
+
+The example above is just a wrapper for the `echo` command-line tool.
+Running the workflow above with the default input values will produce the same result as the
+command-line `echo "Hello World"`.
+
+```{note}
+In CWL, there is a distinction between a command-line tool and a workflow. But
+for the sake of simplicity, we are using the term “workflow” here. You will learn
+more about this in the [basic concepts](basic-concepts.md) section.
+```
+
+## Installing a CWL Runner
+
+`cwltool` is an implementation of the CWL specification. It is also the
+CWL *Reference Runner* for the specification, and it is compliant with the
+latest version of the specification: {{ cwl_version }}. You can install
+`cwltool` using `pip`:
+
+```{code-block} console
+:name: installing-cwltool-with-pip
+:caption: Installing `cwltool` with `pip`.
+
+$ pip install cwltool
+```
+
+```{note}
+If installing the cwltool using the pip command doesn't work for you, the [prerequisites](prerequisites.md) section contains other ways to install `cwltool` and a more detailed list
+of software and libraries used for following the rest of this user guide.
+```
+
+## Running "Hello World"
+
+The usage of the `cwltool` command-line executable is basically
+`cwltool [OPTIONS] [CWL_DOCUMENT] [INPUTS_OBJECT]`. You can run the
+`hello_world.cwl` workflow without specifying any option:
+
+```{runcmd} cwltool hello_world.cwl
+:name: running-hello_world.cwl-with-cwltool
+:caption: Running `hello_world.cwl` with `cwltool`.
+```
+
+Or you can override the default value of the input parameter `message`, similar
+to how you would change the argument of the `echo` base command:
+
+```{runcmd} cwltool hello_world.cwl --message="Hola mundo"
+:name: running-hello_world.cwl-with-cwltool-passing-an-input-parameter
+:caption: Running `hello_world.cwl` with `cwltool` passing an input parameter.
+```
+
+Another way of passing values to your workflow input parameters is via an
+*Inputs Object*. This is a file containing the input fields with their
+corresponding values. The Inputs Objects file can be written in JSON or YAML. For example:
+
+```{literalinclude} /_includes/cwl/hello_world-job.json
+:language: json
+:name: hello_world-job.json
+:caption: "`hello_world-job.json`"
+```
+
+You can use this Inputs Object file now to execute the “Hello World” workflow:
+
+```{runcmd} cwltool hello_world.cwl hello_world-job.json
+:name: passing-an-inputs-object-file-to-cwltool
+:caption: Passing an Inputs Object file to `cwltool`.
+```
+
+```{note}
+We used a similar file name for the workflow and for the Inputs Object files.
+The *-job.json* suffix is very common in Inputs Object files, but it is not
+a requirement. You can choose any name for your workflows and Inputs Object
+files.
+```
+
+## Learn More
+
+Continue reading the next sections of this User Guide!
+- [List of CWL Implementations](https://www.commonwl.org/implementations).
+- The [`common-workflow-language` organization](https://github.com/common-workflow-language) at GitHub.
+- [Common Workflow Language at Wikipedia](https://en.wikipedia.org/wiki/Common_Workflow_Language).
+- [YAML.org](http://yaml.org/) and [YAML at Wikipedia](https://en.wikipedia.org/wiki/YAML).
+- The {{'[CWL Specification VERSION](https://www.commonwl.org/VERSION)'.replace('VERSION', cwl_version_text) }}.
+- [Workflow management system at Wikipedia](https://en.wikipedia.org/wiki/Workflow_management_system).
+
+% N.B.: Wondering what's up with this syntax in the CWL Specification link above?
+% It's necessary as MyST Parser does not allow substitutions in links, for more:
+% - https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-and-urls
+% - https://github.com/executablebooks/MyST-Parser/issues/279
diff --git a/_sources/setup.md.txt b/_sources/setup.md.txt
new file mode 100644
index 00000000..dc8d3f26
--- /dev/null
+++ b/_sources/setup.md.txt
@@ -0,0 +1,12 @@
+---
+orphan: true
+---
+
+# This page has moved
+
+```{attention}
+
+This page is out-of-date and was kept here to preserve the links of the old
+User Guide. The information on this page has been migrated to the
+[FAQ](/faq.md) section of the new user guide.
+```
diff --git a/_sources/topics/additional-arguments-and-parameters.md.txt b/_sources/topics/additional-arguments-and-parameters.md.txt
new file mode 100644
index 00000000..fb39ae06
--- /dev/null
+++ b/_sources/topics/additional-arguments-and-parameters.md.txt
@@ -0,0 +1,51 @@
+# Additional Arguments and Parameters
+
+Sometimes tools require additional command line options that don't
+correspond exactly to input parameters.
+
+In this example, we will wrap the Java compiler to compile a java source
+file to a class file. By default, "javac" will create the class files in
+the same directory as the source file. However, CWL input files (and the
+directories in which they appear) may be read-only, so we need to
+instruct "javac" to write the class file to the designated output directory
+instead.
+
+```{literalinclude} /_includes/cwl/additional-arguments-and-parameters/arguments.cwl
+:language: cwl
+:caption: "`arguments.cwl`"
+:name: arguments.cwl
+```
+
+```{literalinclude} /_includes/cwl/additional-arguments-and-parameters/arguments-job.yml
+:language: yaml
+:caption: "`arguments-job.yml`"
+```
+
+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 `cwltool` providing the tool description and the input object on the command line:
+
+```{runcmd} cwltool arguments.cwl arguments-job.yml
+:working-directory: src/_includes/cwl/additional-arguments-and-parameters
+```
+
+Here we use the `arguments` field to add an additional argument to the
+command line that isn't tied to a specific input parameter.
+
+```cwl
+arguments: ["-d", $(runtime.outdir)]
+```
+
+This example references a runtime parameter. Runtime parameters provide
+information about the hardware or software environment when the tool is
+actually executed. The `$(runtime.outdir)` parameter is the path to the
+designated output directory. Other parameters include `$(runtime.tmpdir)`,
+`$(runtime.ram)`, `$(runtime.cores)`, `$(runtime.outdirSize)`, and
+`$(runtime.tmpdirSize)`. See the [Runtime Environment][runtime] section of the
+CWL specification for details.
+
+[runtime]: https://www.commonwl.org/v1.0/CommandLineTool.html#Runtime_environment
diff --git a/_sources/topics/best-practices.md.txt b/_sources/topics/best-practices.md.txt
new file mode 100644
index 00000000..52bb5097
--- /dev/null
+++ b/_sources/topics/best-practices.md.txt
@@ -0,0 +1,115 @@
+# Best Practices
+
+The following are a set of recommended good practices to keep in mind when writing a
+Common Workflow Language description for a tool or workflow. These guidelines
+are presented for consideration on a scale of usefulness: although more is better, not
+all are required.
+
+- No `type: string` parameters for names of input or reference
+ files/directories; use `type: File` or `type: Directory` as appropriate.
+
+- A CWL document (in conjunction with any external components like `Dockerfile`s) is software code.
+ Workflow developers should be aware that the usual rules of software licensing apply to this
+ document. For example, if the workflow is shared publicly, licensing terms must be clear so that
+ a future user understands under what conditions they can run the workflow, modify it and/or
+ combine it with other workflows. For this reason, please consider including a license field in the
+ document. The authors of this guide urge you to choose a pre-existing license rather than trying
+ to write your own (see the link below to learn more about choosing a license), and our recommended
+ practice is to choose a license that allows for re-use by anyone, e.g. [Apache 2.0][apache-license].
+
+ If possible, the license should be specified with its corresponding [SPDX identifier][spdx].
+ Construct the metadata field for the license by providing a URL of the form
+ `https://spdx.org/licenses/[SPDX-ID]` where `SPDX-ID` is taken from the list of identifiers
+ linked above. See the example snippet below for guidance. For non-standard licenses without an SPDX
+ identifier, provide a URL to the license.
+
+ Useful reading: "[A Quick Guide to Software Licensing for the Scientist-Programmer][sci-license]"
+
+ _Example of metadata field for license with SPDX identifier:_
+
+ ```cwl
+ $namespaces:
+ s: https://schema.org/
+ s:license: https://spdx.org/licenses/Apache-2.0
+ # other s: declarations
+ ```
+
+ For more examples of providing metadata within CWL descriptions, see
+ [the Metadata and Authorship section of this User Guide](../topics/metadata-and-authorship.md).
+
+- Include [attribution information][license-example] for the author(s) of
+ the CWL tool or workflow description. Use unambiguous identifiers like
+ [ORCID][orcid].
+
+- In tool descriptions, list dependencies using short name(s) under
+ [`SoftwareRequirement`](https://w3id.org/cwl/CommandLineTool.html#SoftwareRequirement).
+
+- Include [SciCrunch][scicrunch] identifiers for dependencies in
+ `https://identifiers.org/rrid/RRID:SCR_NNNNNN` format.
+
+- All `input` and `output` identifiers should reflect their conceptual
+ identity. Use informative names like `unaligned_sequences`, `reference_genome`,
+ `phylogeny`, or `aligned_sequences` instead of `foo_input`, `foo_file`,
+ `result`, `input`, `output`, and so forth.
+
+- In tool descriptions, include a list of version(s) of the tool that are
+ known to work with this description under [`SoftwareRequirement`](https://w3id.org/cwl/CommandLineTool.html#SoftwareRequirement).
+
+- `format` should be specified for all input and output `File`s.
+ Bioinformatics tools should use format identifiers from [EDAM][edam-example].
+ See also `iana:text/plain`, `iana:text/tab-separated-values` with
+ `$namespaces: { iana: "https://www.iana.org/assignments/media-types/" }`.
+ [Full IANA media type list][iana-types] (also known as MIME types). For
+ non-bioinformatics tools, use or build an appropriate ontology/controlled
+ vocabulary in the same way. Please edit this page to let us know about it.
+
+- Mark all input and output `File`s that are read from or written to in a
+ streaming compatible way (only once, no random-access), as `streamable: true`.
+
+- Each [`CommandLineTool`](https://w3id.org/cwl/CommandLineTool.html#CommandLineTool) description should focus on a single operation
+ only, even if the (sub)command is capable of more. Don't overcomplicate your
+ tool descriptions with options that you don't need or use.
+
+- Custom types should be defined with one external YAML per type
+ definition for re-use.
+
+- Include a top-level short `label` summarising the tool/workflow.
+
+- If useful, include a top-level `doc` as well. This should provide a
+ longer, more detailed description than was provided in the top-level `label`
+ (see above).
+
+- Use `type: enum` instead of `type: string` for elements with a fixed
+ list of valid values.
+
+- Evaluate all use of JavaScript for possible elimination or replacement.
+ One common example: manipulating `File` names and paths? Consider whether one
+ of the [built in `File` properties][file-prop] like `basename`, `nameroot`,
+ `nameext`, etc., could be used instead.
+
+- Give the tool description to a colleague (preferably at a different
+ institution) to test and provide feedback.
+
+- Complex workflows with individual components which can be abstracted
+ should utilise the [`SubworkflowFeatureRequirement`][subworkflow] to make their
+ workflow modular and allow sections of them to be easily reused.
+
+- Software containers should be made to be conformant to the ["Recommendations for the packaging and containerizing of bioinformatics software"][containers] (also useful to other disciplines).
+
+[containers]: https://doi.org/10.12688/f1000research.15140.1
+[apache-license]: https://spdx.org/licenses/Apache-2.0.html
+[license-example]: https://github.com/ProteinsWebTeam/ebi-metagenomics-cwl/blob/master/workflows/emg-assembly.cwl#L200
+[scicrunch]: https://scicrunch.org
+[edam-example]: http://edamontology.org/format_1915
+[iana-types]: https://www.iana.org/assignments/media-types/media-types.xhtml
+[file-prop]: https://www.commonwl.org/v1.0/CommandLineTool.html#File
+[orcid]: https://orcid.org
+[subworkflow]: https://www.commonwl.org/v1.0/Workflow.html#SubworkflowFeatureRequirement
+[spdx]: https://spdx.org/licenses/
+[sci-license]: https://doi.org/10.1371/journal.pcbi.1002598
+
+% TODO
+%
+% - Writing CWL workflows (include existing docs from https://github.com/common-workflow-library/cwl-patterns/blob/main/README.md)
+% - FAIR best practices with CWL
+% - Docker best practices with CWL - https://github.com/common-workflow-language/common-workflow-language/issues/347
diff --git a/_sources/topics/command-line-tool.md.txt b/_sources/topics/command-line-tool.md.txt
new file mode 100644
index 00000000..c4391994
--- /dev/null
+++ b/_sources/topics/command-line-tool.md.txt
@@ -0,0 +1,86 @@
+# Command Line Tool
+
+A command-line tool is a type of Process object that can be run by
+itself or as a Workflow step. It is a wrapper for a command like
+`ls`, `echo`, `tar`, etc. The command-line tool is defined in the
+`baseCommand` attribute of the command-line tool CWL document.
+
+A CWL command-line tool must also have `inputs` and `outputs`.
+The following example contains a minimal example of a CWL
+command-line tool for the `echo` Linux command, using inputs and
+outputs.
+
+% TODO: Fix the missing link the graph below. We cannot have
+% it here as this file is included in two other files.
+% Sphinx prohibits it for the case where this could lead
+% to duplicate anchors in a page (e.g. single-html).
+% :name: command-line-tool-graph
+
+```{graphviz}
+:caption: CWL command-line tool.
+:align: center
+
+digraph G {
+ compound=true;
+ rankdir="LR";
+ fontname="Verdana";
+ fontsize="10";
+ graph [splines=ortho];
+
+ node [fontname="Verdana", fontsize="10", shape=box];
+ edge [fontname="Verdana", fontsize="10"];
+
+ subgraph cluster_0 {
+ command[style="filled" label=<echo>];
+ label="baseCommand";
+ fill=gray;
+ }
+
+ inputs -> command [lhead=cluster_0];
+ command -> outputs [ltail=cluster_0];
+}
+```
+
+% TODO: Fix the missing link the code below. We cannot have
+% it here as this file is included in two other files.
+% Sphinx prohibits it for the case where this could lead
+% to duplicate anchors in a page (e.g. single-html).
+% :name: echo.cwl
+
+```{literalinclude} /_includes/cwl/echo.cwl
+:language: cwl
+:caption: "`echo.cwl`"
+```
+
+```{note}
+
+The example above uses a simplified form to define inputs and outputs.
+You will learn more about in the [Inputs](../topics/inputs.md)
+and in the [Outputs](../topics/outputs.md) sections.
+```
+
+% TODO
+%
+% - Spaces in commands https://github.com/common-workflow-language/user_guide/issues/39
+% - Arguments (tell the reader the different use cases for arguments and inputs, tell them there is a section about inputs)
+
+
+## Network Access
+This indicates whether a process requires outgoing IPv4/IPv6 network
+access. Starting with CWL v1.1, programs are not granted network
+access by default, so you must include the requirement for network
+access in the specification of your tool.
+
+```cwl
+cwlVersion: v1.2
+class: CommandLineTool
+
+requirements:
+ NetworkAccess:
+ networkAccess: true
+```
+
+```{note}
+CWL v1.0 command-line tools that are upgraded to v1.1
+or v1.2 or v1.2 will have `networkAccess: true` set automatically.
+```
diff --git a/_sources/topics/creating-files-at-runtime.md.txt b/_sources/topics/creating-files-at-runtime.md.txt
new file mode 100644
index 00000000..b2929e2e
--- /dev/null
+++ b/_sources/topics/creating-files-at-runtime.md.txt
@@ -0,0 +1,63 @@
+# Creating Files at Runtime
+
+Sometimes you need to create a file on the fly from input parameters,
+such as tools that expect to read their input configuration from a file
+rather than the command line parameters, or need a small wrapper shell script.
+
+To generate such files, we can use the [`InitialWorkDirRequirement`](https://w3id.org/cwl/CommandLineTool.html#InitialWorkDirRequirement).
+
+```{literalinclude} /_includes/cwl/creating-files-at-runtime/createfile.cwl
+:language: cwl
+:caption: "`createfile.cwl`"
+:name: createfile.cwl
+```
+
+Any [expressions](../topics/expressions.md) like `$(inputs.message)` are
+expanded by the CWL engine before creating the file.
+Here, insert the value at the input `message`.
+
+```{tip}
+The _CWL expressions_ are independent of any _shell variables_
+used later during command line tool invocation. That means that any genuine
+need for the character `$` must be **escaped** with `\`.
+For instance, `\${PREFIX}` above is expanded to `${PREFIX}` in the generated file
+to be evaluated by the shell script instead of the CWL engine.
+```
+
+To test the above CWL tool, use this job to provide the input value `message`:
+
+```{literalinclude} /_includes/cwl/creating-files-at-runtime/echo-job.yml
+:language: yaml
+:caption: "`echo-job.yml`"
+:name: echo-job.yml
+```
+
+Before we run this, let us look at each step in a little more detail.
+The base command `baseCommand: ["sh", "example.sh"]`
+will execute the command `sh example.sh`.
+This will run the file we create in the shell.
+
+`InitialWorkDirRequirement` requires a `listing`.
+As the `listing` is a YAML array, we need a `-` on the first line of
+each element of the array, in this case we have just one element.
+`entryname:` can have any value,
+but it must match what was specified in the `baseCommand`.
+The final part is `entry:`, this is followed by `|-`
+which is YAML quoting syntax, and means that you are using a multiline string
+(without it, we would need to write the whole script on one line).
+
+```{note}
+
+See the [YAML Guide](../topics/yaml-guide.md#maps) for more about the formatting.
+```
+
+Now invoke `cwltool` with the tool description and the input object on the
+command line:
+
+```{runcmd} cwltool createfile.cwl echo-job.yml
+:working-directory: src/_includes/cwl/creating-files-at-runtime/
+```
+
+```{runcmd} cat output.txt
+:working-directory: src/_includes/cwl/creating-files-at-runtime/
+```
diff --git a/_sources/topics/custom-types.md.txt b/_sources/topics/custom-types.md.txt
new file mode 100644
index 00000000..1dca7d44
--- /dev/null
+++ b/_sources/topics/custom-types.md.txt
@@ -0,0 +1,92 @@
+# Custom Types
+
+Sometimes you may want to write your own custom types for use and reuse in CWL
+descriptions. Use of such custom types can reduce redundancy between multiple
+descriptions that all use the same type, and also allow for additional
+customisation/configuration of a tool/analysis without the need to fiddle with
+the CWL description directly.
+
+The example below is a CWL description of the [biom convert format][biom] tool for
+converting a standard biom table file to hdf5 format.
+
+```{literalinclude} /_includes/cwl/custom-types/custom-types.cwl
+:language: cwl
+:caption: "`custom-types.cwl`"
+:name: custom-types.cwl
+```
+
+```{literalinclude} /_includes/cwl/custom-types/custom-types.yml
+:language: yaml
+:caption: "`custom-types.yml`"
+:name: custom-types.yml
+```
+
+___Note:___ To follow the example below, you need to [download the example input file](https://github.com/common-workflow-language/user_guide/blob/main/src/_includes/cwl/custom-types/rich_sparse_otu_table.biom), *rich_sparse_otu_table.biom* e.g. via `wget`:
+
+```{code-block} console
+$ wget https://github.com/common-workflow-language/user_guide/raw/main/src/_includes/cwl/custom-types/rich_sparse_otu_table.biom
+```
+
+On line 29, in `inputs:table_type`, a list of allowable table options to be used in the
+table conversion are imported as a custom object:
+
+```cwl
+inputs:
+ biom:
+ type: File
+ format: edam:format_3746 # BIOM
+ inputBinding:
+ prefix: --input-fp
+ table_type:
+ type: biom-convert-table.yaml#table_type
+ inputBinding:
+ prefix: --table-type
+```
+
+The reference to a custom type is a combination of the name of the file in which
+the object is defined (`biom-convert-table.yaml`) and the name of the object
+within that file (`table_type`) that defines the custom type. In this case the `symbols`
+array from the imported `biom-convert-table.yaml` file define the allowable table options.
+For example, in `custom-types.yml`, we pass `OTU table` as an `input` that
+tells the tool to create an OTU table in hdf5 format.
+
+The contents of the YAML file describing the custom type are given below:
+
+```{literalinclude} /_includes/cwl/custom-types/biom-convert-table.yaml
+:language: yaml
+:caption: "`biom-convert-table.yaml`"
+:name: biom-convert-table.yaml
+```
+
+In order for the custom type to be used in the CWL description, it must be
+imported. Imports are described in `requirements:SchemaDefRequirement`, as
+below in the example `custom-types.cwl` description:
+
+```cwl
+requirements:
+ InlineJavascriptRequirement: {}
+ ResourceRequirement:
+ coresMax: 1
+ ramMin: 100
+ SchemaDefRequirement:
+ types:
+ - $import: biom-convert-table.yaml
+```
+
+Note also that the author of this CWL description has also included
+[`ResourceRequirement`](https://w3id.org/cwl/CommandLineTool.html#ResourceRequirement)s, specifying the minimum amount of RAM and number of cores
+required for the tool to run successfully, as well as details of the version of
+the software that the description was written for and other useful metadata.
+These features are discussed further in other chapters of this user guide.
+
+[biom]: http://biom-format.org/
+
+% TODO (enums)
+%
+% - https://github.com/common-workflow-language/user_guide/issues/155
+% - Maybe show an example with booleans, pros and cons - https://github.com/common-workflow-language/user_guide/issues/89
+%
+% TODO (records)
+%
+% - https://github.com/common-workflow-language/common-workflow-language/issues/202
+% - Document corner cases & workarounds - https://github.com/common-workflow-language/common-workflow-language/issues/241
diff --git a/_sources/topics/environment-variables.md.txt b/_sources/topics/environment-variables.md.txt
new file mode 100644
index 00000000..a2228029
--- /dev/null
+++ b/_sources/topics/environment-variables.md.txt
@@ -0,0 +1,27 @@
+# Environment Variables
+
+Tools run in a restricted environment and do not inherit most environment
+variables from the parent process. You can set environment variables for
+the tool using `EnvVarRequirement`.
+
+```{literalinclude} /_includes/cwl/environment-variables/env.cwl
+:language: cwl
+:caption: "`env.cwl`"
+:name: env.cwl
+```
+
+```{literalinclude} /_includes/cwl/environment-variables/echo-job.yml
+:language: yaml
+:caption: "`echo-job.yml`"
+```
+
+Now invoke `cwltool` with the tool description and the input object on the
+command line:
+
+```{runcmd} cwltool env.cwl echo-job.yml
+:working-directory: src/_includes/cwl/environment-variables/
+```
+
+```{runcmd} cat output.txt
+:working-directory: src/_includes/cwl/environment-variables/
+```
diff --git a/_sources/topics/expression-tool.md.txt b/_sources/topics/expression-tool.md.txt
new file mode 100644
index 00000000..85cdce3a
--- /dev/null
+++ b/_sources/topics/expression-tool.md.txt
@@ -0,0 +1,74 @@
+# Expression Tool
+
+An expression tool is a type of Process that can be run by itself or
+as a Workflow step. It executes a pure JavaScript expression. It is
+meant to be used as a way to isolate complex JavaScript expressions
+that need to operate on input data and produce some result as output.
+
+Similar to the command-line tool it requires `inputs` and `outputs`.
+But instead of `baseCommand`, it requires an [`expression`](https://w3id.org/cwl/CommandLineTool.html#Expressions_(Optional)) attribute.
+
+% TODO: Fix the missing link the graph below. We cannot have
+% it here as this file is included in two other files.
+% Sphinx prohibits it for the case where this could lead
+% to duplicate anchors in a page (e.g. single-html).
+% :name: expression-tool-graph
+
+```{graphviz}
+:caption: CWL expression tool.
+:align: center
+
+digraph G {
+ compound=true;
+ rankdir="LR";
+ fontname="Verdana";
+ fontsize="10";
+ graph [splines=ortho];
+
+ node [fontname="Verdana", fontsize="10", shape=box];
+ edge [fontname="Verdana", fontsize="10"];
+
+ subgraph cluster_0 {
+ expression[style="filled" label="JavaScript"];
+ label="expression";
+ fill=gray;
+ }
+
+ inputs -> expression [lhead=cluster_0];
+ expression -> outputs [ltail=cluster_0];
+}
+```
+
+% TODO: Fix the missing link the code below. We cannot have
+% it here as this file is included in two other files.
+% Sphinx prohibits it for the case where this could lead
+% to duplicate anchors in a page (e.g. single-html).
+% :name: uppercase.cwl
+
+```{code-block} cwl
+:caption: "`uppercase.cwl`"
+cwlVersion: v1.2
+class: ExpressionTool
+
+requirements:
+ InlineJavascriptRequirement: {}
+
+inputs:
+ message: string
+outputs:
+ uppercase_message: string
+
+expression: |
+ ${ return {"uppercase_message": inputs.message.toUpperCase()}; }
+```
+
+```{note}
+
+We had to use an [`InlineJavascriptRequirement`](https://w3id.org/cwl/CommandLineTool.html#InlineJavascriptRequirement) as our expression
+contains a JavaScript call in `.toUpperCase()`. This means to tools
+using the expression tool that JavaScript is a requirement.
+```
+
+% TODO:
+%
+% - Explain better with more examples.
diff --git a/_sources/topics/expressions.md.txt b/_sources/topics/expressions.md.txt
new file mode 100644
index 00000000..a2dc79ae
--- /dev/null
+++ b/_sources/topics/expressions.md.txt
@@ -0,0 +1,203 @@
+# Expressions
+
+If you need to manipulate input parameters, include the requirement
+[`InlineJavascriptRequirement`](https://w3id.org/cwl/CommandLineTool.html#InlineJavascriptRequirement) and then anywhere a parameter reference is
+legal you can provide a fragment of Javascript that will be evaluated by
+the CWL runner.
+
+```{important}
+JavaScript expressions should only be used when absolutely necessary.
+When manipulating file names, extensions, paths etc, consider whether one of the
+[built in `File` properties][file-prop] like `basename`, `nameroot`, `nameext`,
+etc, could be used instead.
+See the [list of best practices](best-practices.md).
+```
+
+```{literalinclude} /_includes/cwl/expressions/expression.cwl
+:language: cwl
+:caption: "`expression.cwl`"
+:name: expression.cwl
+```
+
+As this tool does not require any `inputs` we can run it with an (almost) empty
+job file:
+
+```{literalinclude} /_includes/cwl/expressions/empty.yml
+:language: yaml
+:caption: "`empty.yml`"
+:name: empty.cwl
+```
+
+`empty.yml` contains a description of an empty JSON object. JSON objects
+descriptions are contained inside curly brackets `{}`, so an empty object is
+represented simply by a set of empty brackets.
+
+We can then run `expression.cwl`:
+
+```{runcmd} cwltool expression.cwl empty.yml
+:name: running-expression.cwl
+:caption: Running `expression.cwl`
+:working-directory: src/_includes/cwl/expressions/
+```
+
+```{runcmd} cat output.txt
+:working-directory: src/_includes/cwl/expressions/
+```
+
+Note that requirements can be provided with the map syntax, as in the example above:
+
+```cwl
+requirements:
+ InlineJavascriptRequirement: {}
+```
+
+Or as an array, with each entry (in this case, only `class: InlineJavascriptRequirement`) marked by a `-`.
+The same syntax is used to describe the additional command line arguments.
+
+```cwl
+requirements:
+ - class: InlineJavascriptRequirement
+```
+
+```{admonition} Where are JavaScript expressions allowed?
+
+Just like [parameter references](parameter-references.md), you can use JavaScript Expressions
+only in certain fields. These are:
+- From [`CommandLineTool`](https://www.commonwl.org/v1.0/CommandLineTool.html#CommandLineTool)
+ - `arguments`
+ - `valueFrom`
+ - `stdin`
+ - `stdout`
+ - `stderr`
+ - From [CommandInputParameter](https://www.commonwl.org/v1.0/CommandLineTool.html#CommandInputParameter)
+ - `format`
+ - `secondaryFiles`
+ - From [`inputBinding`](https://www.commonwl.org/v1.0/CommandLineTool.html#CommandLineBinding)
+ - `valueFrom`
+ - From [CommandOutputParamater](https://www.commonwl.org/v1.0/CommandLineTool.html#CommandOutputParameter)
+ - `format`
+ - `secondaryFiles`
+ - From [CommandOutputBinding](https://www.commonwl.org/v1.0/CommandLineTool.html#CommandOutputBinding)
+ - `glob`
+ - `outputEval`
+- From [`Workflow`](https://w3id.org/cwl/Workflow.html)
+ - From [InputParameter](https://www.commonwl.org/v1.0/Workflow.html#InputParameter) and [WorkflowOutputParameter](https://www.commonwl.org/v1.0/Workflow.html#WorkflowOutputParameter)
+ - `format`
+ - `secondaryFiles`
+ - From `steps`
+ - From [WorkflowStepInput](https://www.commonwl.org/v1.0/Workflow.html#WorkflowStepInput)
+ - `valueFrom`
+- From [ExpressionTool](https://www.commonwl.org/v1.0/Workflow.html#ExpressionTool)
+ - `expression`
+ - From [InputParameter](https://www.commonwl.org/v1.0/Workflow.html#InputParameter) and [ExpressionToolOutputParameter](https://www.commonwl.org/v1.0/Workflow.html#ExpressionToolOutputParameter)
+ - `format`
+ - `secondaryFiles`
+- From [`ResourceRequirement`](https://www.commonwl.org/v1.0/CommandLineTool.html#ResourceRequirement)
+ - `coresMin`
+ - `coresMax`
+ - `ramMin`
+ - `ramMax`
+ - `tmpdirMin`
+ - `tmpdirMax`
+ - `outdirMin`
+ - `outdirMax`
+- From [`InitialWorkDirRequirement`](https://www.commonwl.org/v1.0/CommandLineTool.html#InitialWorkDirRequirement)
+ - `listing`
+ - in [Dirent](https://www.commonwl.org/v1.0/CommandLineTool.html#Dirent)
+ - `entry`
+ - `entryname`
+- From `EnvVarRequirement`
+ - From [EnvironmentDef](https://www.commonwl.org/v1.0/CommandLineTool.html#EnvironmentDef)
+ - `envValue`
+```
+
+[file-prop]: https://www.commonwl.org/v1.0/CommandLineTool.html#File
+
+## Using External Libraries and Inline JavaScript Code with `expressionLib`
+
+The requirement [`InlineJavascriptRequirement`](https://w3id.org/cwl/CommandLineTool.html#InlineJavascriptRequirement) supports an `expressionLib` attribute
+that allows users to load external JavaScript files, or to provide inline JavaScript
+code.
+
+Entries added to the `expressionLib` attribute are parsed with the JavaScript engine
+of a CWL runner. This can be used to include external files or to create JavaScript
+functions that can be called in other parts of the CWL document.
+
+```{note}
+
+The CWL standards (versions 1.0 through 1.2) [states](https://www.commonwl.org/v1.0/CommandLineTool.html#Expressions)
+ that the only version of JavaScript valid in CWL expressions is
+[ECMAScript 5.1](https://262.ecma-international.org/5.1/). This means that any
+code that you include or write in your CWL Document must be compliant with
+ECMAScript 5.1.
+```
+
+For example, we can use `InlineJavascriptRequirement` and write a JavaScript function
+inline in `expressionLib`. That function can then be used in other parts of the
+CWL document:
+
+```{literalinclude} /_includes/cwl/expressions/hello-world-expressionlib-inline.cwl
+:language: cwl
+:caption: "`hello-world-expressionlib-inline.cwl`"
+:name: "`hello-world-expressionlib-inline.cwl`"
+:emphasize-lines: 5, 14, 32
+```
+
+Running this CWL workflow will invoke the JavaScript function and result in
+the `echo` command printing the input message with capital initial letters:
+
+```{runcmd} cwltool hello-world-expressionlib-inline.cwl --message "hello world"
+:caption: "Running `hello-world-expressionlib-inline.cwl`."
+:name: running-hell-world-expressionlib-inline-cwl
+:working-directory: src/_includes/cwl/expressions/
+```
+
+Let's move the `capitalizeWords` function to an external file, `custom-functions.js`, and
+import it in our CWL document:
+
+```{literalinclude} /_includes/cwl/expressions/custom-functions.js
+:language: javascript
+:caption: "`custom-functions.js`"
+:name: "`custom-functions.js`"
+```
+
+```{literalinclude} /_includes/cwl/expressions/hello-world-expressionlib-external.cwl
+:language: cwl
+:caption: "`hello-world-expressionlib-external.cwl`"
+:name: "`hello-world-expressionlib-external.cwl`"
+:emphasize-lines: 5-6, 14
+```
+
+The `custom-functions.js` file is included in the CWL document with the `$include: custom-functions.js`
+statement. That makes the functions and variables available to be used in other parts of
+the CWL document.
+
+```{runcmd} cwltool hello-world-expressionlib-external.cwl --message "hello world"
+:caption: "Running `hello-world-expressionlib-external.cwl`."
+:name: running-hell-world-expressionlib-external-cwl
+:working-directory: src/_includes/cwl/expressions/
+```
+
+Finally, note that you can have both inline and external JavaScript code in your
+CWL document. In this final example we have added another entry to the `expressionLib`
+attribute with the new function `createHelloWorldMessage`, that calls the `capitalizeWords`
+function from the external file `custom-functions.js`.
+
+```{literalinclude} /_includes/cwl/expressions/hello-world-expressionlib.cwl
+:language: cwl
+:caption: "`hello-world-expressionlib.cwl`"
+:name: "`hello-world-expressionlib.cwl`"
+:emphasize-lines: 5-17, 25
+```
+
+```{runcmd} cwltool hello-world-expressionlib.cwl --message "hello world"
+:caption: "Running `hello-world-expressionlib.cwl`."
+:name: running-hell-world-expressionlib-cwl
+:working-directory: src/_includes/cwl/expressions/
+```
+
+```{note}
+The `$include` statement can be used to include a file from the local disk or from a remote location.
+It works with both relative and absolute paths. Read the [text about `$include`](https://www.commonwl.org/v1.0/SchemaSalad.html#Include)
+from the CWL specification to learn more about it.
+```
diff --git a/_sources/topics/file-formats.md.txt b/_sources/topics/file-formats.md.txt
new file mode 100644
index 00000000..e1d0f5fa
--- /dev/null
+++ b/_sources/topics/file-formats.md.txt
@@ -0,0 +1,60 @@
+# File Formats
+
+Tools and workflows can take [`File`](https://w3id.org/cwl/CommandLineTool.html#File) types as input and produce them as output.
+We also recommend indicating the format for [`File`](https://w3id.org/cwl/CommandLineTool.html#File) types. This helps document
+for others how to use your tool while allowing you to do some simple
+type-checking when creating parameter files.
+
+For file formats, we recommend referencing existing ontologies (like EDAM in
+our example), reference a local ontology for your institution, or do not add
+a file format initially for quick development before sharing your tool with
+others. You can browse existing [IANA file format listings][IANA] and
+[EDAM file format listings][EDAM] on their websites.
+
+In the next tutorial, we explain the `$namespaces` and `$schemas` section of the
+document in greater detail, so don't worry about these for now.
+
+Note that for added value `cwltool` can do some basic reasoning based on file
+formats and warn you if there seem to be some obvious mismatches.
+
+```{literalinclude} /_includes/cwl/file-formats/metadata_example.cwl
+:language: cwl
+:caption: "`metadata_example.cwl`"
+:name: metadata_example.cwl
+```
+
+The equivalent of this CWL description in command line format is:
+
+```{code-block} console
+$ wc -l /path/to/aligned_sequences.ext > output.txt
+```
+
+## Sample Parameter Files
+
+Below is an example of a parameter file for the example above. We encourage
+checking in working examples of parameter files for your tool. This allows
+others to quickly work with your tool, starting from a "known good"
+parameterization.
+
+```{literalinclude} /_includes/cwl/file-formats/sample.yml
+:language: yaml
+:caption: "`sample.yml`"
+:name: sample.yml
+```
+
+___Note:___ To follow the example below, you need to download the example input file, *file-formats.bam*. The file is available from
+ and can be downloaded e.g. via `wget`:
+
+```{code-block}
+$ wget https://github.com/common-workflow-language/user_guide/raw/main/src/_includes/cwl/file-formats/file-formats.bam
+```
+
+Now invoke `cwltool` with the tool description and the input object on the
+command line:
+
+```{runcmd} cwltool metadata_example.cwl sample.yml
+:working-directory: src/_includes/cwl/file-formats/
+```
+
+[IANA]: https://www.iana.org/assignments/media-types/media-types.xhtml
+[EDAM]: https://www.ebi.ac.uk/ols/ontologies/edam/terms?iri=http%3A%2F%2Fedamontology.org%2Fformat_1915
diff --git a/_sources/topics/index.md.txt b/_sources/topics/index.md.txt
new file mode 100644
index 00000000..09ec4142
--- /dev/null
+++ b/_sources/topics/index.md.txt
@@ -0,0 +1,25 @@
+# Topics
+
+```{toctree}
+:maxdepth: 2
+yaml-guide.md
+command-line-tool.md
+expressions.md
+inputs.md
+additional-arguments-and-parameters.md
+parameter-references.md
+outputs.md
+custom-types.md
+expression-tool.md
+workflows.md
+operations.md
+environment-variables.md
+using-containers.md
+creating-files-at-runtime.md
+staging-input-files.md
+best-practices.md
+file-formats.md
+metadata-and-authorship.md
+specifying-software-requirements.md
+troubleshooting.md
+```
diff --git a/_sources/topics/inputs.md.txt b/_sources/topics/inputs.md.txt
new file mode 100644
index 00000000..e4e162b9
--- /dev/null
+++ b/_sources/topics/inputs.md.txt
@@ -0,0 +1,309 @@
+# Inputs
+
+## Essential Input Parameters
+
+The `inputs` of a tool is a list of input parameters that control how to
+run the tool. Each parameter has an `id` for the name of parameter, and
+`type` describing what types of values are valid for that parameter.
+
+Available primitive types are *string*, *boolean*, *int*, *long*, *float*, *double*,
+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.
+
+First, create a file called `inp.cwl`, containing the following:
+
+```{literalinclude} /_includes/cwl/inputs/inp.cwl
+:language: cwl
+:caption: "`inp.cwl`"
+:name: inp.cwl
+```
+
+Create a file called `inp-job.yml`:
+
+```{literalinclude} /_includes/cwl/inputs/inp-job.yml
+:language: yaml
+:caption: "`inp-job.yml`"
+:name: 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 an input object file:
+
+```{runcmd} cwltool --make-template inp.cwl
+:working-directory: src/_includes/cwl/inputs
+```
+
+You can redirect the output to a file, i.e. `cwltool --make-template inp.cwl > inp-job.yml`,
+and then modify the default values with your desired input values.
+````
+
+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.
+
+```{code-block} console
+$ touch whale.txt
+```
+
+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:
+
+```{runcmd} cwltool inp.cwl inp-job.yml
+:working-directory: src/_includes/cwl/inputs
+```
+
+```{tip}
+
Where did those `/tmp` paths come from?
+
+The CWL reference runner (cwltool) and other runners create temporary
+directories with symbolic ("soft") links to your input files to ensure that
+the tools aren't accidentally accessing files that were not explicitly
+specified
+```
+
+The field [`inputBinding`](https://w3id.org/cwl/CommandLineTool.html#Input_binding) is optional and indicates whether 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.
+
+```cwl
+example_flag:
+ type: boolean
+ inputBinding:
+ position: 1
+ prefix: -f
+```
+
+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.
+
+```cwl
+example_string:
+ type: string
+ inputBinding:
+ position: 3
+ prefix: --example-string
+```
+
+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
+rendered as `--example-string hello`.
+
+```cwl
+example_int:
+ type: int
+ inputBinding:
+ position: 2
+ prefix: -i
+ separate: false
+```
+
+Integer (and floating point) types appear on the command line with
+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`.
+
+
+```cwl
+example_file:
+ type: File?
+ inputBinding:
+ prefix: --file=
+ separate: false
+ position: 4
+```
+
+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 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
+[first copy it to the output directory](staging-input-files.md).
+
+The value of `position` is used to determine where 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
+line as 1, 2, 3. More than one parameter can have the same position
+(ties are broken using the parameter name), and the position field itself
+is optional. The default position is 0.
+
+The `baseCommand` field will always appear in the final command line before the parameters.
+
+[touch]: http://www.linfo.org/touch.html
+
+## 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.
+
+```{literalinclude} /_includes/cwl/inputs/array-inputs.cwl
+:language: cwl
+:caption: "`array-inputs.cwl`"
+:name: array-inputs.cwl
+```
+
+```{literalinclude} /_includes/cwl/inputs/array-inputs-job.yml
+:language: yaml
+:caption: "`array-inputs-job.yml`"
+:name: array-inputs-job.yml
+```
+
+Now invoke `cwltool` providing the tool description and the input object
+on the command line:
+
+```{runcmd} cwltool array-inputs.cwl array-inputs-job.yml
+:working-directory: src/_includes/cwl/inputs/
+```
+
+```{code-block} console
+$ cat output.txt
+-A one two three -B=four -B=five -B=six -C=seven,eight,nine
+```
+
+The `inputBinding` can appear either on the outer array parameter definition
+or the inner array element definition, and these produce different behavior when
+constructing the command line, as shown above.
+In addition, the `itemSeparator` field, if provided, specifies that array
+values should be concatenated into a single argument separated by the item
+separator string.
+
+Note that the arrays of inputs are specified inside square brackets `[]` in `array-inputs-job.yml`. Arrays can also be expressed over multiple lines, where
+array values that are not defined with an associated key are marked by a leading `-`.
+This will be demonstrated in the next lesson
+and is discussed in more detail in the [YAML Guide](yaml-guide.md#arrays).
+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 exclusive). You can use records and type unions to group
+parameters together to describe these two conditions.
+
+```{literalinclude} /_includes/cwl/inputs/record.cwl
+:language: cwl
+:caption: "`record.cwl`"
+:name: record.cwl
+```
+
+```{literalinclude} /_includes/cwl/inputs/record-job1.yml
+:language: yaml
+:caption: "`record-job1.yml`"
+:name: record-job1.yml
+```
+
+```{runcmd} cwltool record.cwl record-job1.yml
+:working-directory: src/_includes/cwl/inputs/
+:emphasize-lines: 6-7
+```
+
+In the first example, you can't provide `itemA` without also providing `itemB`.
+
+```{literalinclude} /_includes/cwl/inputs/record-job2.yml
+:language: yaml
+:caption: "`record-job2.yml`"
+:name: record-job2.yml
+```
+
+```{runcmd} cwltool record.cwl record-job2.yml
+:working-directory: src/_includes/cwl/inputs
+:emphasize-lines: 4, 10-11, 23
+```
+
+```{code-block} console
+$ cat output.txt
+-A one -B two -C three
+```
+
+In the second example, `itemC` and `itemD` are exclusive, so only the first
+matching item (`itemC`) is added to the command line and remaining item (`itemD`) is ignored.
+
+```{literalinclude} /_includes/cwl/inputs/record-job3.yml
+:language: yaml
+:caption: "`record-job3.yml`"
+:name: record-job3.yml
+```
+
+```{runcmd} cwltool record.cwl record-job3.yml
+:working-directory: src/_includes/cwl/inputs
+:emphasize-lines: 9-10, 21
+```
+
+```{code-block} console
+$ cat output.txt
+-A one -B two -D four
+```
+
+In the third example, only `itemD` is provided, so it appears on the
+command line.
+
+### Exclusive Input Parameters with Expressions
+
+If you use exclusive input parameters and reference them in expressions, you
+need to be aware that the `inputs` JavaScript object will contain one of the
+possible, mutually-exclusive input values. Because the types of these exclusive
+values may differ, you may need to check which type is in use when you
+reference the properties of the `input` object.
+
+Let's use an example that contains an exclusive `file_format` input parameter
+that accepts `null` (i.e. no value provided), or any value from an enum.
+
+```{literalinclude} /_includes/cwl/inputs/exclusive-parameter-expressions.cwl
+:language: cwl
+:caption: "`exclusive-parameter-expressions.cwl`"
+:name: exclusive-parameter-expressions.cwl
+```
+
+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 possible values of the enum), your
+command should execute successfully:
+
+```{runcmd} cwltool exclusive-parameter-expressions.cwl --file_format fasta
+:working-directory: src/_includes/cwl/inputs
+```
+
+However, if you do not provide any input value, then `file_format` will be
+evaluated to `null`, which does not match the expected type for the
+output field (a `string`), resulting in failure when running your workflow.
+
+```{runcmd} cwltool exclusive-parameter-expressions.cwl
+:working-directory: src/_includes/cwl/inputs
+:emphasize-lines: 5-10
+```
+
+To correct it, you should explicitly handle the possibility of a `null` value.
+For example, the expression could be changed to `$(inputs.file_format ||
+'auto')`, to have a default value `"auto"` if none was provided in the command
+line or job input file.
+
+Here, the boolean “or” operator `||` in JavaScript is used for its
+_short-circuiting_ property. If `inputs.file_format` is “true” in a boolean
+context (e.g. a valid non-empty string from the enum), the evaluation of the
+expression stops at the first operand of `||`; it “short-circuits”. If however
+`inputs.file_format` is `null`, the whole expression’s value becomes that of
+the second operand, which is why a reasonable default can be provided there.
+
+% TODO
+%
+% - Explain its fields, such as default, valueFrom, etc. - https://github.com/common-workflow-language/common-workflow-language/issues/359
+% - Optional Inputs https://github.com/common-workflow-language/user_guide/issues/44
+% - 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
diff --git a/_sources/topics/metadata-and-authorship.md.txt b/_sources/topics/metadata-and-authorship.md.txt
new file mode 100644
index 00000000..57850533
--- /dev/null
+++ b/_sources/topics/metadata-and-authorship.md.txt
@@ -0,0 +1,42 @@
+# Metadata and Authorship
+
+Implementation extensions not required for correct execution (for example,
+fields related to GUI presentation) and metadata about the tool or workflow
+itself (for example, authorship for use in citations) may be provided as
+additional fields on any object. Such extensions fields (e.g. `format: edam:format_2572`)
+can use a namespace prefix listed in the `$namespaces` section of the document
+(e.g. edam: http://edamontology.org/) as described in the [Schema Salad specification][schema-salad].
+Once you add the namespace prefix, you can access it anywhere in the document as shown below.
+Otherwise, one must use full URLs: `format: http://edamontology.org/format_2572`.
+
+
+For all developers, we recommend the following minimal metadata for your tool
+and workflows. This example includes metadata allowing others to cite your tool.
+
+```{literalinclude} /_includes/cwl/metadata-and-authorship/metadata_example2.cwl
+:language: cwl
+:caption: "`metadata_example2.cwl`"
+:name: metadata_example2.cwl
+```
+
+The equivalent of this CWL description in command line format is:
+
+```{code-block}
+$ wc -l /path/to/aligned_sequences.ext > output.txt
+```
+
+## Extended Example
+
+For those that are highly motivated, it is also possible to annotate your tool
+with a much larger amount of metadata. This example includes EDAM ontology tags
+as keywords (allowing the grouping of related tools), hints at hardware
+requirements in order to use the tool, and a few more metadata fields.
+
+```{literalinclude} /_includes/cwl/metadata-and-authorship/metadata_example3.cwl
+:language: cwl
+:caption: "`metadata_example3.cwl`"
+:name: metadata_example3.cwl
+:emphasize-lines: 8-10, 47-48
+```
+
+[schema-salad]: https://www.commonwl.org/v1.0/SchemaSalad.html#Explicit_context
diff --git a/_sources/topics/operations.md.txt b/_sources/topics/operations.md.txt
new file mode 100644
index 00000000..1d601eba
--- /dev/null
+++ b/_sources/topics/operations.md.txt
@@ -0,0 +1,69 @@
+# Operations
+
+An Operation is a type of CWL process, just like a workflow, a command-line tool, or
+an expression tool. It is a step of a workflow that specifies inputs and outputs,
+but it does not provide enough information to be executed.
+
+You can create operations to visualize a workflow during development, before
+you are ready to submit the workflow to a CWL runner:
+
+```{literalinclude} /_includes/cwl/operations/operations.cwl
+:language: cwl
+:name: operations.cwl
+:caption: "`operations.cwl`"
+```
+
+The `uppercase` step of the workflow is an operation. It can appear where a
+command line tool or an expression is expected. You can also plot it with the
+CWL Viewer or `cwltool`:
+
+```{runcmd} cwltool --print-dot operations.cwl
+:working-directory: src/_includes/cwl/operations/
+```
+
+The output of the command above can be rendered `cwltool --print-dot operations.cwl | dot -Tsvg >
+operations.svg ; open operations.svg`.
+
+```{graphviz}
+
+digraph G {
+bgcolor="#eeeeee";
+clusterrank=local;
+labeljust=right;
+labelloc=bottom;
+"echo" [fillcolor=lightgoldenrodyellow, label=echo, shape=record, style=filled];
+"uppercase" [fillcolor=lightgoldenrodyellow, label=uppercase, shape=record, style=dashed];
+"echo" -> "uppercase";
+subgraph cluster_inputs {
+label="Workflow Inputs";
+rank=same;
+style=dashed;
+"message" [fillcolor="#94DDF4", label=message, shape=record, style=filled];
+}
+
+"message" -> "echo";
+subgraph cluster_outputs {
+label="Workflow Outputs";
+labelloc=b;
+rank=same;
+style=dashed;
+}
+
+}
+```
+
+The operation file will fail to run with `cwltool` because `cwltool`
+lacks the necessary information to execute it:
+
+```{runcmd} cwltool operations.cwl --message Hello
+:working-directory: src/_includes/cwl/operations/
+:name: operations-output-error-cwltool
+:caption: "`cwltool` does not know how to run operations"
+```
+
+```{note}
+
+CWL runners may come up with ways to bind operations to concrete steps.
+A CWL runner could, for instance, use abstract operations with ID's that
+correspond to steps executed by a different workflow engine.
+```
diff --git a/_sources/topics/outputs.md.txt b/_sources/topics/outputs.md.txt
new file mode 100644
index 00000000..b2513f32
--- /dev/null
+++ b/_sources/topics/outputs.md.txt
@@ -0,0 +1,123 @@
+# Outputs
+
+## Returning Output Files
+
+The `outputs` of a tool is a list of output parameters that should be
+returned after running the tool. Each parameter has an `id` for the name
+of parameter, and `type` describing what types of values are valid for
+that parameter.
+
+When a tool runs under CWL, the starting working directory is the
+designated output directory. The underlying tool or script must record
+its results in the form of files created in the output directory. The
+output parameters returned by the CWL tool are either the output files
+themselves, or the result of examining the content of those files.
+
+The following example demonstrates how to return a file that has been extracted from a tar file.
+
+```{tip}
+Passing mandatory arguments to the `baseCommand`
+
+In previous examples, the `baseCommand` was just a string, with any arguments
+passed as CWL inputs. Instead of a single string, we can use an _array of
+strings_ as the value of `baseCommand`. The first element of the array is the
+command to run, and any subsequent elements are mandatory command line
+arguments
+```
+
+```{literalinclude} /_includes/cwl/outputs/tar.cwl
+:language: cwl
+:caption: "`tar.cwl`"
+:name: tar.cwl
+```
+
+```{literalinclude} /_includes/cwl/outputs/tar-job.yml
+:language: yaml
+:caption: "`tar-job.yml`"
+:name: tar-job.yml
+```
+
+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 `cwltool` with the tool description and the input object on the command line:
+
+```{runcmd} cwltool tar.cwl tar-job.yml
+:working-directory: src/_includes/cwl/outputs/
+```
+
+The field [`outputBinding`](https://w3id.org/cwl/CommandLineTool.html#CommandOutputBinding) describes how to set the value of each
+output parameter.
+
+```cwl
+outputs:
+ example_out:
+ type: File
+ outputBinding:
+ glob: hello.txt
+```
+
+The [`glob`](https://w3id.org/cwl/CommandLineTool.html#CommandOutputBinding)
+field consists of the pattern to match file names in the output directory.
+This can simply be the file's exact name. But if you don't know the name of the
+file in advance, you can use a wildcard pattern like `glob: '*.txt'`.
+
+## Capturing Standard Output
+
+To capture a tool's standard output stream, add the [`stdout`](https://w3id.org/cwl/CommandLineTool.html#stdout) field with
+the name of the file where the output stream should go. Then add `type:
+stdout` on the corresponding output parameter.
+
+```{literalinclude} /_includes/cwl/outputs/stdout.cwl
+:language: cwl
+:caption: "`stdout.cwl`"
+:name: stdout.cwl
+```
+
+```{literalinclude} /_includes/cwl/outputs/echo-job.yml
+:language: yaml
+:caption: "`echo-job.yml`"
+```
+
+Now invoke `cwltool` providing the tool description and the input object
+on the command line:
+
+```{runcmd} cwltool stdout.cwl echo-job.yml
+:working-directory: src/_includes/cwl/outputs/
+```
+
+## Array Outputs
+
+You can also capture multiple output files into an array of files using `glob`.
+
+```{literalinclude} /_includes/cwl/outputs/array-outputs.cwl
+:language: cwl
+:caption: "`array-outputs.cwl`"
+:name: array-outputs.cwl
+```
+
+```{literalinclude} /_includes/cwl/outputs/array-outputs-job.yml
+:language: yaml
+:caption: "`array-outputs-job.yml`"
+:name: array-outputs-job.yml
+```
+
+Now invoke `cwltool` providing the tool description and the input object
+on the command line:
+
+```{runcmd} cwltool array-outputs.cwl array-outputs-job.yml
+:working-directory: src/_includes/cwl/outputs/
+```
+
+As described in the [YAML Guide](yaml-guide.md#arrays),
+the array of expected outputs is specified in `array-outputs-job.yml` with each
+entry marked by a leading `-`. This format can also be used in CWL descriptions
+to mark entries in arrays, as demonstrated in several of the upcoming sections.
+
+% TODO
+%
+% - Creating files at runtime - https://github.com/common-workflow-language/user_guide/issues/134
diff --git a/_sources/topics/parameter-references.md.txt b/_sources/topics/parameter-references.md.txt
new file mode 100644
index 00000000..d901029e
--- /dev/null
+++ b/_sources/topics/parameter-references.md.txt
@@ -0,0 +1,109 @@
+# Parameter References
+
+In a previous example, we extracted a file using the "tar" program.
+However, that example was very limited because it assumed that the file
+we were interested in was called "hello.txt", and this was written into the
+`.cwl` file. This is not the best way to do this, as the "hello.txt" filename
+may vary or be dependent on the input file(s) used. To avoid this we can
+specify the name of the file we want in the job parameters file (`.yml`). In
+this example, you will see how to reference the value of input parameters
+dynamically from other fields, which will allow us to then specify the name of
+the file to extract.
+
+```{literalinclude} /_includes/cwl/parameter-references/tar-param.cwl
+:language: cwl
+:caption: "`tar-param.cwl`"
+:name: tar-param.cwl
+```
+
+```{literalinclude} /_includes/cwl/parameter-references/tar-param-job.yml
+:language: yaml
+:caption: "`tar-param-job.yml`"
+:name: tar-param-job.yml
+```
+
+Create your input files and invoke `cwltool` with the tool description and the
+input object on the command line:
+
+```{code-block} console
+$ rm hello.tar || true && touch goodbye.txt && tar -cvf hello.tar goodbye.txt
+```
+
+```{runcmd} cwltool tar-param.cwl tar-param-job.yml
+:working-directory: src/_includes/cwl/parameter-references
+```
+
+Certain fields permit parameter references which are enclosed in `$(...)`.
+These are evaluated and replaced with value being referenced.
+
+```cwl
+outputs:
+ extracted_out:
+ type: File
+ outputBinding:
+ glob: $(inputs.extractfile)
+```
+
+References are written using a subset of Javascript syntax. In this
+example, `$(inputs.extractfile)`, `$(inputs["extractfile"])`, and
+`$(inputs['extractfile'])` are equivalent.
+
+The value of the "inputs" variable is the input object provided when the
+CWL tool was invoked.
+
+Note that because `File` parameters are objects, to get the path to an
+input file you must reference the path field on a file object; to
+reference the path to the tar file in the above example you would write
+`$(inputs.tarfile.path)`.
+
+```{admonition} Where are parameter references allowed?
+
+You can only use parameter references in certain fields. These are:
+
+- From [`CommandLineTool`](http://www.commonwl.org/v1.0/CommandLineTool.html#CommandLineTool)
+ - `arguments`
+ - `valueFrom`
+ - `stdin`
+ - `stdout`
+ - `stderr`
+ - From [CommandInputParameter](http://www.commonwl.org/v1.0/CommandLineTool.html#CommandInputParameter)
+ - `format`
+ - `secondaryFiles`
+ - From [`inputBinding`](http://www.commonwl.org/v1.0/CommandLineTool.html#CommandLineBinding)
+ - `valueFrom`
+ - From [CommandOutputParamater](http://www.commonwl.org/v1.0/CommandLineTool.html#CommandOutputParameter)
+ - `format`
+ - `secondaryFiles`
+ - From [CommandOutputBinding](http://www.commonwl.org/v1.0/CommandLineTool.html#CommandOutputBinding)
+ - `glob`
+ - `outputEval`
+- From [`Workflow`](https://w3id.org/cwl/Workflow.html)
+ - From [InputParameter](http://www.commonwl.org/v1.0/Workflow.html#InputParameter) and [WorkflowOutputParameter](http://www.commonwl.org/v1.0/Workflow.html#WorkflowOutputParameter)
+ - `format`
+ - `secondaryFiles`
+ - From `steps`
+ - From [WorkflowStepInput](http://www.commonwl.org/v1.0/Workflow.html#WorkflowStepInput)
+ - `valueFrom`
+- From [ExpressionTool](https://www.commonwl.org/v1.0/Workflow.html#ExpressionTool)
+ - `expression`
+ - From [InputParameter](http://www.commonwl.org/v1.0/Workflow.html#InputParameter) and [ExpressionToolOutputParameter](http://www.commonwl.org/v1.0/Workflow.html#ExpressionToolOutputParameter)
+ - `format`
+ - `secondaryFiles`
+- From [`ResourceRequirement`](http://www.commonwl.org/v1.0/CommandLineTool.html#ResourceRequirement)
+ - `coresMin`
+ - `coresMax`
+ - `ramMin`
+ - `ramMax`
+ - `tmpdirMin`
+ - `tmpdirMax`
+ - `outdirMin`
+ - `outdirMax`
+- From [`InitialWorkDirRequirement`](http://www.commonwl.org/v1.0/CommandLineTool.html#InitialWorkDirRequirement)
+ - `listing`
+ - in [Dirent](http://www.commonwl.org/v1.0/CommandLineTool.html#Dirent)
+ - `entry`
+ - `entryname`
+- From `EnvVarRequirement`
+ - From [EnvironmentDef](http://www.commonwl.org/v1.0/CommandLineTool.html#EnvironmentDef)
+ - `envValue`
+```
diff --git a/_sources/topics/requirements-and-hints.md.txt b/_sources/topics/requirements-and-hints.md.txt
new file mode 100644
index 00000000..c46c96d9
--- /dev/null
+++ b/_sources/topics/requirements-and-hints.md.txt
@@ -0,0 +1,28 @@
+---
+orphan: true
+---
+
+# Requirements and Hints
+
+% TODO
+%
+% - InlineJavascriptRequirement
+% - Maybe list cases where it is not really necessary? e.g. https://github.com/common-workflow-language/common-workflow-language/issues/389
+% - Covered by the **episode 13** of the current User Guide - https://www.commonwl.org/user_guide/13-expressions/index.html
+% - InitialWorkDirRequirement
+% - Staging Files (a common topic, and appears in questions on discourse/element... maybe it deserves a more prominent location?)
+% - Writable inputs - https://github.com/common-workflow-language/user_guide/issues/36
+% - Creating files at runtime, from **episode 14** of the current User Guide - https://www.commonwl.org/user_guide/14-runtime/index.html
+% - There is a whole **episode 15** in the current User Guide about it - https://www.commonwl.org/user_guide/15-staging/index.html
+% - DockerRequirement
+% - Covered in the **episode 7** of the current User Guide - https://www.commonwl.org/user_guide/07-containers/index.html
+% - SchemaDefRequirement and input schemas
+% - The **episode 19** from the current User Guide covers it - https://www.commonwl.org/user_guide/19-custom-types/index.html
+% - ShellCommandRequirement - https://github.com/common-workflow-language/user_guide/issues/159
+% - SoftwareRequirement - From the **20** from the current User Guide - episode https://www.commonwl.org/user_guide/20-software-requirements/index.html
+% - MultipleInputFeatureRequirement
+% - Also in **episode 24** of the current User Guide - https://www.commonwl.org/user_guide/24_conditional-workflow/index.html
+% - SubworkflowFeatureRequirement
+% - Also in **episode 22** of the current User Guide - https://www.commonwl.org/user_guide/22-nested-workflows/index.html
+% - ScatterFeatureRequirement
+% - Also in **episode 23** of the current User Guide - https://www.commonwl.org/user_guide/23-scatter-workflow/index.html
diff --git a/_sources/topics/specifying-software-requirements.md.txt b/_sources/topics/specifying-software-requirements.md.txt
new file mode 100644
index 00000000..bebd3596
--- /dev/null
+++ b/_sources/topics/specifying-software-requirements.md.txt
@@ -0,0 +1,44 @@
+# Specifying Software Requirements
+
+Often, tool descriptions will be written for a specific version of a software. To
+make it easier for others to use your descriptions, you can include a
+[`SoftwareRequirement`](https://w3id.org/cwl/CommandLineTool.html#SoftwareRequirement) field in the `hints` section.
+This may also help to avoid confusion about which version of a tool the
+description was written for.
+
+```{literalinclude} /_includes/cwl/specifying-software-requirements/custom-types.cwl
+:language: cwl
+```
+
+In this example, the software requirement being described is InterProScan
+version 5.21-60.
+
+```cwl
+hints:
+ SoftwareRequirement:
+ packages:
+ interproscan:
+ specs: [ "https://identifiers.org/rrid/RRID:SCR_005829" ]
+ version: [ "5.21-60" ]
+```
+
+Depending on your CWL runner, these hints may be used to check
+that the required software is installed and available before the job is run. To enable
+these checks with the reference implementation, use the [dependency resolvers configuration][dependencies].
+
+As well as a version number, a unique resource identifier (URI) for the tool is
+given in the form of an [RRID][rrid]. Resources with RRIDs can be looked up in the
+[SciCrunch][scicrunch] registry, which provides a portal for finding, tracking,
+and referring to scientific resources consistently. If you want to specify a
+tool as a [`SoftwareRequirement`](https://w3id.org/cwl/CommandLineTool.html#SoftwareRequirement), search for the tool on SciCrunch and use the
+RRID that it has been assigned in the registry. (Follow this [Adding a Resource Tutorial][scicrunch-add-tool] to add a tool to SciCrunch). You can use this RRID to refer
+to the tool (via [identifiers.org][identifiers]) in the `specs` field of your
+requirement description. Other good choices, in order of preference, are to
+include the DOI for the main tool citation and the URL to the tool.
+
+
+[rrid]: https://scicrunch.org/resources/about/resource
+[scicrunch]: https://scicrunch.org/
+[dependencies]: https://github.com/common-workflow-language/cwltool#leveraging-softwarerequirements-beta
+[identifiers]: https://identifiers.org/
+[scicrunch-add-tool]: https://scicrunch.org/page/tutorials/336
diff --git a/_sources/topics/staging-input-files.md.txt b/_sources/topics/staging-input-files.md.txt
new file mode 100644
index 00000000..8d4812b2
--- /dev/null
+++ b/_sources/topics/staging-input-files.md.txt
@@ -0,0 +1,25 @@
+# Staging Input Files
+
+Normally, input files are located in a read-only directory separate from
+the output directory. This causes problems if the underlying tool expects to
+write its output files alongside the input file in the same directory. You use [`InitialWorkDirRequirement`](https://w3id.org/cwl/CommandLineTool.html#InitialWorkDirRequirement) to stage input files into the output directory.
+In this example, we use a JavaScript expression to extract the base name of the
+input file from its leading directory path.
+
+```{literalinclude} /_includes/cwl/staging-input-files/linkfile.cwl
+:language: cwl
+:caption: "`linkfile.cwl`"
+:name: linkfile.cwl
+```
+
+```{literalinclude} /_includes/cwl/staging-input-files/arguments-job.yml
+:language: yaml
+:caption: "`arguments-job.yml`"
+```
+
+Now invoke `cwltool` with the tool description and the input object on the
+command line:
+
+```{runcmd} cwltool linkfile.cwl arguments-job.yml
+:working-directory: src/_includes/cwl/staging-input-files/
+```
diff --git a/_sources/topics/troubleshooting.md.txt b/_sources/topics/troubleshooting.md.txt
new file mode 100644
index 00000000..d9543fa8
--- /dev/null
+++ b/_sources/topics/troubleshooting.md.txt
@@ -0,0 +1,63 @@
+# Troubleshooting
+
+In this section you will find ways to troubleshoot when you have problems executing CWL.
+We focus on `cwltool` here but some of these techniques may apply to other CWL Runners.
+
+## Run `cwltool` with `cachedir`
+
+You can use the `--cachedir` option when running a workflow to tell `cwltool` to
+cache intermediate files (files that are not input nor output files, but created
+while your workflow is running). By default, these files are created in a
+temporary directory but writing them to a separate directory makes accessing
+them easier.
+
+In the following example `troubleshooting-wf1.cwl` we have two steps, `step_a` and `step_b`.
+The workflow is equivalent to `echo "Hello World" | rev`, which would print the message
+"Hello World" reversed, i.e. "dlroW olleH". However, the second step, `step_b`, **has a typo**,
+where instead of executing the `rev` command it tries to execute `revv`, which
+fails.
+
+```{literalinclude} /_includes/cwl/troubleshooting/troubleshooting-wf1.cwl
+:language: cwl
+:name: "`troubleshooting-wf1.cwl`"
+:caption: "`troubleshooting-wf1.cwl`"
+:emphasize-lines: 42
+```
+
+Let's execute this workflow with `/tmp/cachedir/` as the `--cachedir` value (`cwltool` will
+create the directory for you if it does not exist already):
+
+```{runcmd} cwltool --cachedir /tmp/cachedir/ troubleshooting-wf1.cwl
+:working-directory: src/_includes/cwl/troubleshooting
+:emphasize-lines: 13-15, 18-20
+```
+
+The workflow is in the `permanentFail` status due to `step_b` failing to execute the
+non-existent `revv` command. The `step_a` was executed successfully and its output
+has been cached in your `cachedir` location. You can inspect the intermediate files
+created:
+
+```{runcmd} tree /tmp/cachedir
+:emphasize-lines: 4
+```
+
+Each workflow step has received a unique ID (the long value that looks like a hash).
+The `${HASH}.status` files display the status of each step executed by the workflow.
+And the `step_a` output file `stdout.txt` is visible in the output of the command above.
+
+Now fix the typo so `step_b` executes `rev` (i.e. replace `revv` by `rev` in the
+`step_b`). After fixing the typo, when you execute `cwltool` with the same arguments
+as the previous time, note that now `cwltool` output contains information about
+pre-cached outputs for `step_a`, and about a new cache entry for the output of `step_b`.
+Also note that the status of `step_b` is now of success.
+
+```{runcmd} cwltool --cachedir /tmp/cachedir/ troubleshooting-wf1-stepb-fixed.cwl
+:working-directory: src/_includes/cwl/troubleshooting
+:emphasize-lines: 12-16
+```
+
+In this example the workflow step `step_a` was not re-evaluated as it had been cached, and
+there was no change in its execution or output. Furthermore, `cwltool` was able to recognize
+when it had to re-evaluate `step_b` after we fixed the executable name. This technique is
+useful for troubleshooting your CWL documents and also as a way to prevent `cwltool` to
+re-evaluate steps unnecessarily.
diff --git a/_sources/topics/using-containers.md.txt b/_sources/topics/using-containers.md.txt
new file mode 100644
index 00000000..5b47df68
--- /dev/null
+++ b/_sources/topics/using-containers.md.txt
@@ -0,0 +1,76 @@
+# Using Containers
+
+## Running Tools Inside Docker
+
+[Docker][docker] containers simplify software installation by providing a
+complete known-good runtime for software and its dependencies. However,
+containers are also purposefully isolated from the host system, so in
+order to run a tool inside a Docker container there is additional work to
+ensure that input files are available inside the container and output
+files can be recovered from the container. A CWL runner can perform this work
+automatically, allowing you to use Docker to simplify your software
+management while avoiding the complexity of invoking and managing Docker
+containers.
+
+One of the responsibilities of the CWL runner is to adjust the paths of
+input files to reflect the location where they appear inside the container.
+
+This example runs a simple Node.js script inside a Docker container which will
+then print "Hello World" to the standard output.
+
+```{literalinclude} /_includes/cwl/using-containers/docker.cwl
+:language: cwl
+:caption: "`docker.cwl`"
+:name: docker.cwl
+```
+
+```{literalinclude} /_includes/cwl/using-containers/docker-job.yml
+:language: yaml
+:caption: "`docker-job.yml`"
+:name: docker-job.yml
+```
+
+Before we run this, let's just break it down and see what some bits do. Most of this
+has been explained in previous sections, the only part that is really new is the [`dockerRequirement`](https://w3id.org/cwl/CommandLineTool.html#DockerRequirement)
+section.
+
+```cwl
+baseCommand: node
+hints:
+ DockerRequirement:
+ dockerPull: node:slim
+```
+
+`baseCommand: node` tells CWL that we will be running this command using the Node Js runtime that is meant for Javascript files. We
+then need to specify some `hints` for how to find the container we want. In this case we list
+just our requirements for the docker container in `DockerRequirements`. The `dockerPull:`
+parameter takes the same value that you would pass to a `docker pull` command. That is,
+the name of the container image (you can even specify the tag, which is good idea for
+best practices when using containers for reproducible research). In this case we have
+used a container called `node:slim`.
+
+Create a Javascript file named "hello.js" and invoke `cwltool` providing the tool description and the
+input object on the command line:
+
+```{literalinclude} /_includes/cwl/using-containers/hello.js
+:language: javascript
+:caption: "`hello.js`"
+:name: hello.js
+```
+
+```{runcmd} cwltool docker.cwl docker-job.yml
+:working-directory: src/_includes/cwl/using-containers/
+```
+
+```{runcmd} cat output.txt
+:working-directory: src/_includes/cwl/using-containers/
+```
+
+Notice the CWL runner has constructed a Docker command line to run the
+script.
+
+In this example, the path to the script `hello.js` is `/home/me/cwl/user_guide/hello.js`
+outside the container but `/var/lib/cwl/job369354770_examples/hello.js` inside
+the container, as reflected in the invocation of the `node` command.
+
+[docker]: https://docker.io
diff --git a/_sources/topics/workflows.md.txt b/_sources/topics/workflows.md.txt
new file mode 100644
index 00000000..ff7c02d5
--- /dev/null
+++ b/_sources/topics/workflows.md.txt
@@ -0,0 +1,651 @@
+# Workflows
+
+A workflow is a CWL processing unit that executes command-line tools,
+expression tools, or workflows (sub-workflows) as steps. It must have
+`inputs`, `outputs`, and `steps` defined in the CWL document.
+
+% TODO: Fix the missing link the graph below. We cannot have
+% it here as this file is included in two other files.
+% Sphinx prohibits it for the case where this could lead
+% to duplicate anchors in a page (e.g. single-html).
+% :name: workflow-graph
+
+```{graphviz}
+:caption: CWL workflow.
+:align: center
+
+digraph G {
+ compound=true;
+ rankdir="LR";
+ fontname="Verdana";
+ fontsize="10";
+ graph [splines=ortho];
+
+ node [fontname="Verdana", fontsize="10", shape=box];
+ edge [fontname="Verdana", fontsize="10"];
+
+ subgraph cluster_0 {
+ node [width = 1.75];
+ steps_0[style="filled" label="Command-line tools"];
+ steps_1[style="filled" label="Expression tools"];
+ steps_2[style="filled" label="Sub-workflows"];
+ label="steps";
+ fill=gray;
+ }
+
+ inputs -> steps_1 [lhead=cluster_0];
+ steps_1 -> outputs [ltail=cluster_0];
+}
+```
+
+The CWL document `echo-uppercase.cwl` defines a workflow that runs
+the command-line tool, and the expression tool showed in the earlier
+examples.
+
+% TODO: Fix the missing link the code below. We cannot have
+% it here as this file is included in two other files.
+% Sphinx prohibits it for the case where this could lead
+% to duplicate anchors in a page (e.g. single-html).
+% :name: echo-uppercase.cwl
+
+```{code-block} cwl
+:caption: "`echo-uppercase.cwl`"
+cwlVersion: v1.2
+class: Workflow
+
+requirements:
+ InlineJavascriptRequirement: {}
+
+inputs:
+ message: string
+
+outputs:
+ out:
+ type: string
+ outputSource: uppercase/uppercase_message
+
+steps:
+ echo:
+ run: echo.cwl
+ in:
+ message: message
+ out: [out]
+ uppercase:
+ run: uppercase.cwl
+ in:
+ message:
+ source: echo/out
+ out: [uppercase_message]
+```
+
+A command-line tool or expression tool can also be written directly
+in the same CWL document as the workflow. For example, we can rewrite
+the `echo-uppercase.cwl` workflow as a single file:
+
+% TODO: Fix the missing link the code below. We cannot have
+% it here as this file is included in two other files.
+% Sphinx prohibits it for the case where this could lead
+% to duplicate anchors in a page (e.g. single-html).
+% :name: echo-uppercase-single-file.cwl
+
+```{code-block} cwl
+:caption: "`echo-uppercase-single-file.cwl`"
+cwlVersion: v1.2
+class: Workflow
+
+requirements:
+ InlineJavascriptRequirement: {}
+
+inputs:
+ message: string
+
+outputs:
+ out:
+ type: string
+ outputSource: uppercase/uppercase_message
+
+steps:
+ echo:
+ run:
+ class: CommandLineTool
+
+ baseCommand: echo
+
+ stdout: output.txt
+
+ inputs:
+ message:
+ type: string
+ inputBinding: {}
+ outputs:
+ out:
+ type: string
+ outputBinding:
+ glob: output.txt
+ loadContents: true
+ outputEval: $(self[0].contents)
+ in:
+ message: message
+ out: [out]
+ uppercase:
+ run:
+ class: ExpressionTool
+
+ requirements:
+ InlineJavascriptRequirement: {}
+
+ inputs:
+ message: string
+ outputs:
+ uppercase_message: string
+
+ expression: |
+ ${ return {"uppercase_message": inputs.message.toUpperCase()}; }
+ in:
+ message:
+ source: echo/out
+ out: [uppercase_message]
+```
+
+Having separate files helps with modularity and code organization. But
+it can be helpful writing everything in a single file for development.
+There are other ways to combine multiple files into a single file
+(e.g. `cwltool --pack`) discussed further in other sections of this
+user guide.
+
+% TODO: add a link to the page about SubworkflowFeatureRequirement
+
+```{note}
+
+For a sub-workflows you need to enable the requirement
+`SubworkflowFeatureRequirement`. It is covered in another section
+of this user guide in more detail.
+```
+
+## Writing Workflows
+
+This workflow extracts a java source file from a tar file and then
+compiles it.
+
+```{literalinclude} /_includes/cwl/workflows/1st-workflow.cwl
+:language: cwl
+:caption: "`1st-workflow.cwl`"
+:name: 1st-workflow.cwl
+```
+
+% TODO: The link below is for a previous commit with the workflow above. Ideally, I think we should either use `cwltool`
+% or Python to add the graph here. Or, maybe re-create the graph for the latest main version?
+
+```{admonition} Visualization of 1st-workflow.cwl
+[](https://view.commonwl.org/graph/png/github.com/common-workflow-language/user_guide/blob/a29e7eae0006660946fc705a310b37a21a7e1edc/_includes/cwl/21-1st-workflow/1st-workflow.cwl)
+```
+
+Use a YAML or a JSON object in a separate file to describe the input of a run:
+
+```{literalinclude} /_includes/cwl/workflows/1st-workflow-job.yml
+:language: yaml
+:caption: "`1st-workflow-job.yml`"
+:name: 1st-workflow-job.yml
+```
+
+Next, create a sample Java file and add it to a tar file to use with the command-line tool.
+
+```{code-block} console
+$ echo "public class Hello {}" > Hello.java && tar -cvf hello.tar Hello.java
+Hello.java
+```
+
+Now invoke `cwltool` with the tool description and the input object on the
+command line:
+
+```{runcmd} cwltool 1st-workflow.cwl 1st-workflow-job.yml
+:working-directory: src/_includes/cwl/workflows/
+```
+
+What's going on here? Let's break it down:
+
+```cwl
+cwlVersion: v1.0
+class: Workflow
+```
+
+The `cwlVersion` field indicates the version of the CWL spec used by the
+document. The `class` field indicates this document describes a workflow.
+
+```cwl
+inputs:
+ tarball: File
+ name_of_file_to_extract: string
+```
+
+The `inputs` section describes the inputs of the workflow. This is a
+list of input parameters where each parameter consists of an identifier
+and a data type. These parameters can be used as sources for input to
+specific workflows steps.
+
+```cwl
+outputs:
+ compiled_class:
+ type: File
+ outputSource: compile/classfile
+```
+
+The `outputs` section describes the outputs of the workflow. This is a
+list of output parameters where each parameter consists of an identifier
+and a data type. The `outputSource` connects the output parameter `classfile`
+of the `compile` step to the workflow output parameter `compiled_class`.
+
+```cwl
+steps:
+ untar:
+ run: tar-param.cwl
+ in:
+ tarfile: tarball
+ extractfile: name_of_file_to_extract
+ out: [extracted_file]
+```
+
+The `steps` section describes the actual steps of the workflow. In this
+example, the first step extracts a file from a tar file, and the second
+step compiles the file from the first step using the java compiler.
+Workflow steps are not necessarily run in the order they are listed,
+instead the order is determined by the dependencies between steps (using
+`source`). In addition, workflow steps which do not depend on one
+another may run in parallel.
+
+The first step, `untar` runs `tar-param.cwl` (described previously in
+[Parameter References](parameter-references.md)).
+This tool has two input parameters, `tarfile` and `extractfile` and one output
+parameter `extracted_file`.
+
+The ``in`` section of the workflow step connects these two input parameters to
+the inputs of the workflow, `tarball` and `name_of_file_to_extract` using
+`source`. This means that when the workflow step is executed, the values
+assigned to `tarball` and `name_of_file_to_extract` will be used for the
+parameters `tarfile` and `extractfile` in order to run the tool.
+
+The `out` section of the workflow step lists the output parameters that are
+expected from the tool.
+
+```cwl
+ compile:
+ run: arguments.cwl
+ in:
+ src: untar/extracted_file
+ out: [classfile]
+```
+
+The second step `compile` depends on the results from the first step by
+connecting the input parameter `src` to the output parameter of `untar` using
+`untar/extracted_file`. It runs `arguments.cwl` (described previously in
+[Additional Arguments and Parameters](additional-arguments-and-parameters.md)).
+The output of this step `classfile` is connected to the
+`outputs` section for the Workflow, described above.
+
+## Nested Workflows
+
+Workflows are ways to combine multiple tools to perform a larger operations.
+We can also think of a workflow as being a tool itself; a CWL workflow can be
+used as a step in another CWL workflow, if the workflow engine supports the
+`SubworkflowFeatureRequirement`:
+
+```cwl
+requirements:
+ SubworkflowFeatureRequirement: {}
+```
+
+Here's an example workflow that uses our `1st-workflow.cwl` as a nested
+workflow:
+
+```{literalinclude} /_includes/cwl/workflows/nestedworkflows.cwl
+:language: cwl
+:caption: "`nestedworkflows.cwl`"
+:name: nestedworkflows.cwl
+```
+
+```{note}
+
Visualization of the workflow and the inner workflow from its `compile` step
+
+This two-step workflow starts with the `create-tar` step which is connected to
+the `compile` step in orange; `compile` is another workflow, diagrammed on the
+right. In purple we see the fixed string `"Hello.java"` being supplied as the
+`name_of_file_to_extract`.
+
+
+
+```
+
+A CWL `Workflow` can be used as a `step` just like a `CommandLineTool`, its CWL
+file is included with `run`. The workflow inputs (`tarball` and `name_of_file_to_extract`) and outputs
+(`compiled_class`) then can be mapped to become the step's input/outputs.
+
+```cwl
+ compile:
+ run: 1st-workflow.cwl
+ in:
+ tarball: create-tar/tar_compressed_java_file
+ name_of_file_to_extract:
+ default: "Hello.java"
+ out: [compiled_class]
+```
+
+Our `1st-workflow.cwl` was parameterized with workflow inputs, so when running
+it we had to provide a job file to denote the tar file and `*.java` filename.
+This is generally best-practice, as it means it can be reused in multiple parent
+workflows, or even in multiple steps within the same workflow.
+
+Here we use `default:` to hard-code `"Hello.java"` as the `name_of_file_to_extract`
+input, however our workflow also requires a tar file at `tarball`, which we will
+prepare in the `create-tar` step. At this point it is probably a good idea to refactor
+`1st-workflow.cwl` to have more specific input/output names, as those also
+appear in its usage as a tool.
+
+It is also possible to do a less generic approach and avoid external
+dependencies in the job file. So in this workflow we can generate a hard-coded
+`Hello.java` file using the previously mentioned `InitialWorkDirRequirement`
+requirement, before adding it to a tar file.
+
+```cwl
+ create-tar:
+ requirements:
+ InitialWorkDirRequirement:
+ listing:
+ - entryname: Hello.java
+ entry: |
+ public class Hello {
+ public static void main(String[] argv) {
+ System.out.println("Hello from Java");
+ }
+ }
+```
+
+In this case our step can assume `Hello.java` rather than be parameterized, so
+we can use hardcoded values `hello.tar` and `Hello.java` in a `baseCommand` and
+the resulting `outputs`:
+
+```cwl
+ run:
+ class: CommandLineTool
+ inputs: []
+ baseCommand: [tar, --create, --file=hello.tar, Hello.java]
+ outputs:
+ tar_compressed_java_file:
+ type: File
+ streamable: true
+ outputBinding:
+ glob: "hello.tar"
+```
+
+Did you notice that we didn't split out the `tar --create` tool to a separate file,
+but rather embedded it within the CWL Workflow file? This is generally not best
+practice, as the tool then can't be reused. The reason for doing it in this case
+is because the command line is hard-coded with filenames that only make sense
+within this workflow.
+
+In this example we had to prepare a tar file outside, but only because our inner
+workflow was designed to take that as an input. A better refactoring of the
+inner workflow would be to take a list of Java files to compile, which would
+simplify its usage as a tool step in other workflows.
+
+Nested workflows can be a powerful feature to generate higher-level functional
+and reusable workflow units - but just like for creating a CWL Tool description,
+care must be taken to improve its usability in multiple workflows.
+
+## Scattering Steps
+
+Now that we know how to write workflows, we can start utilizing the `ScatterFeatureRequirement`.
+This feature tells the runner that you wish to run a tool or workflow multiple times over a list
+of inputs. The workflow then takes the input(s) as an array and will run the specified step(s)
+on each element of the array as if it were a single input. This allows you to run the same workflow
+on multiple inputs without having to generate many different commands or input yaml files.
+
+```cwl
+requirements:
+ ScatterFeatureRequirement: {}
+```
+
+The most common reason a new user might want to use scatter is to perform the same analysis on
+different samples. Let's start with a simple workflow that calls our first example
+(`hello_world.cwl`) and takes an array of strings as input to the workflow:
+
+```{literalinclude} /_includes/cwl/workflows/scatter-workflow.cwl
+:language: cwl
+:caption: "`scatter-workflow.cwl`"
+:name: scatter-workflow.cwl
+```
+
+Aside from the `requirements` section including `ScatterFeatureRequirement`, what is
+going on here?
+
+```cwl
+inputs:
+ message_array: string[]
+```
+
+First of all, notice that the main workflow level input here requires an array of strings.
+
+```cwl
+steps:
+ echo:
+ run: hello_world.cwl
+ scatter: message
+ in:
+ message: message_array
+ out: []
+```
+
+Here we've added a new field to the step `echo` called `scatter`. This field tells the
+runner that we'd like to scatter over this input for this particular step. Note that
+the input name listed after scatter is the one of the step's input, not a workflow level input.
+
+For our first scatter, it's as simple as that! Since our tool doesn't collect any outputs, we
+still use `outputs: []` in our workflow, but if you expect that the final output of your
+workflow will now have multiple outputs to collect, be sure to update that to an array type
+as well!
+
+Using the following input file:
+
+```{literalinclude} /_includes/cwl/workflows/scatter-job.yml
+:language: yaml
+:caption: "`scatter-job.yml`"
+:name: scatter-job.yml
+```
+
+As a reminder, [`hello_world.cwl`](../introduction/quick-start.md) simply calls the command
+`echo` on a message. If we invoke `cwltool scatter-workflow.cwl scatter-job.yml` on the
+command line:
+
+```{runcmd} cwltool scatter-workflow.cwl scatter-job.yml
+:working-directory: src/_includes/cwl/workflows/
+```
+
+You can see that the workflow calls echo multiple times on each element of our
+`message_array`. Ok, so how about if we want to scatter over two steps in a workflow?
+
+Let's perform a simple echo like above, but capturing `stdout` by adding the following
+lines instead of `outputs: []`
+
+```{code-block} cwl
+:caption: "`hello_world_to_stdout.cwl`"
+:name: hello_world_to_stdout.cwl
+outputs:
+ echo_out:
+ type: stdout
+```
+
+And add a second step that uses `wc` to count the characters in each file. See the tool
+below:
+
+```{literalinclude} /_includes/cwl/workflows/wc-tool.cwl
+:language: cwl
+:caption: "`wc-tool.cwl`"
+:name: wc-tool.cwl
+```
+
+Now, how do we incorporate scatter? Remember the scatter field is under each step:
+
+```{literalinclude} /_includes/cwl/workflows/scatter-two-steps.cwl
+:language: cwl
+:caption: "`scatter-two-steps.cwl`"
+:name: scatter-two-steps.cwl
+```
+
+Here we have placed the scatter field under each step. This is fine for this example since
+it runs quickly, but if you're running many samples for a more complex workflow, you may
+wish to consider an alternative. Here we are running scatter on each step independently, but
+since the second step is not dependent on the first step completing all languages, we aren't
+using the scatter functionality efficiently. The second step expects an array as input from
+the first step, so it will wait until everything in step one is finished before doing anything.
+Pretend that `echo Hello World!` takes 1 minute to perform, `wc -c` on the output takes 3 minutes
+and that `echo Hallo welt!` takes 5 minutes to perform, and `wc` on that output takes 3 minutes.
+Even though `echo Hello World!` could finish in 4 minutes, it will actually finish in 8 minutes
+because the first step must wait on `echo Hallo welt!`. You can see how this might not scale
+well.
+
+Ok, so how do we scatter on steps that can proceed independent of other samples? Remember from
+[Nested Workflows](#nested-workflows), that we can make an entire workflow a single step in another workflow! Convert our
+two-step workflow to a single step subworkflow:
+
+```{literalinclude} /_includes/cwl/workflows/scatter-nested-workflow.cwl
+:language: cwl
+:caption: "`scatter-nested-workflow.cwl`"
+:name: scatter-nested-workflow.cwl
+```
+
+Now the scatter acts on a single step, but that step consists of two steps so each step is performed
+in parallel.
+
+## Conditional Workflows
+
+This workflow contains a conditional step and is executed based on the input.
+This allows workflows to skip additional steps based on input parameters given at the start of the program or by previous steps.
+
+```{code-block} cwl
+:caption: "`conditional-workflow.cwl`"
+:name: conditional-workflow.cwl
+class: Workflow
+cwlVersion: v1.2
+inputs:
+ val: int
+
+steps:
+
+ step1:
+ in:
+ in1: val
+ a_new_var: val
+ run: foo.cwl
+ when: $(inputs.in1 < 1)
+ out: [out1]
+
+ step2:
+ in:
+ in1: val
+ a_new_var: val
+ run: foo.cwl
+ when: $(inputs.a_new_var > 2)
+ out: [out1]
+
+outputs:
+ out1:
+ type: string
+ outputSource:
+ - step1/out1
+ - step2/out1
+ pickValue: first_non_null
+
+requirements:
+ InlineJavascriptRequirement: {}
+ MultipleInputFeatureRequirement: {}
+```
+
+The first thing you'll notice is that this workflow is only compatible for version 1.2 or greater of the CWL standards.
+
+```cwl
+class: Workflow
+cwlVersion: v1.2
+```
+
+The first step of the workflow (step1) contains two input properties and will execute foo.cwl when the conditions are met. The new property `when` is where the condition validation takes place. In this case only when `in1` from the workflow contains a value `< 1` this step will be executed.
+
+```cwl
+steps:
+
+ step1:
+ in:
+ in1: val
+ a_new_var: val
+ run: foo.cwl
+ when: $(inputs.in1 < 1)
+ out: [out1]
+```
+
+Using the following command `cwltool cond-wf-003.1.cwl --val 0` the value will pass the first conditional step and will therefore be executed and is shown in the log by `INFO [step step1] start` whereas the second step is skipped as indicated by `INFO [step step2] will be skipped`.
+
+```{code-block} console
+INFO [workflow ] start
+INFO [workflow ] starting step step1
+INFO [step step1] start
+INFO [job step1] /private/tmp/docker_tmpdcyoto2d$ echo
+
+INFO [job step1] completed success
+INFO [step step1] completed success
+INFO [workflow ] starting step step2
+INFO [step step2] will be skipped
+INFO [step step2] completed skipped
+INFO [workflow ] completed success
+{
+ "out1": "foo 0"
+}
+INFO Final process status is success
+```
+
+When a value of 3 is given the first conditional step will not be executed but the second step will `cwltool cond-wf-003.1.cwl --val 3`.
+
+```{code-block} console
+INFO [workflow ] start
+INFO [workflow ] starting step step1
+INFO [step step1] will be skipped
+INFO [step step1] completed skipped
+INFO [workflow ] starting step step2
+INFO [step step2] start
+INFO [job step2] /private/tmp/docker_tmpqwr93mxx$ echo
+
+INFO [job step2] completed success
+INFO [step step2] completed success
+INFO [workflow ] completed success
+{
+ "out1": "foo 3"
+}
+INFO Final process status is success
+```
+
+If no conditions are met for example when using `--val 2` the workflow will raise a permanentFail.
+
+```{code-block} console
+$ cwltool cond-wf-003.1.cwl --val 2
+
+INFO [workflow ] start
+INFO [workflow ] starting step step1
+INFO [step step1] will be skipped
+INFO [step step1] completed skipped
+INFO [workflow ] starting step step2
+INFO [step step2] will be skipped
+INFO [step step2] completed skipped
+ERROR [workflow ] Cannot collect workflow output: All sources for 'out1' are null
+INFO [workflow ] completed permanentFail
+WARNING Final process status is permanentFail
+```
+
+% TODO
+% - Scatter
+% - ScatterMethod https://github.com/common-workflow-language/user_guide/issues/29
+% - Also in the **episode 23** of the current User Guide - https://www.commonwl.org/user_guide/workflows/index.html
+% - Subworkflows/nested workflows
+% - Covered in the **episode 22** from the current User Guide - https://www.commonwl.org/user_guide/workflows/index.html
+% - Conditionals https://github.com/common-workflow-language/user_guide/issues/191 & https://github.com/common-workflow-language/user_guide/issues/188
+% - Also in the **episode 24** of the current User Guide - https://www.commonwl.org/user_guide/24_conditional-workflow/index.html
diff --git a/_sources/topics/yaml-guide.md.txt b/_sources/topics/yaml-guide.md.txt
new file mode 100644
index 00000000..9475f83a
--- /dev/null
+++ b/_sources/topics/yaml-guide.md.txt
@@ -0,0 +1,203 @@
+# YAML Guide
+
+
+
+
+[YAML][yaml] is a file format
+designed to be readable by both computers and humans.
+This guide introduces the features of YAML that are
+relevant when writing CWL descriptions and input parameter files.
+
+```{note}
+
+You can skip this section if you are already comfortable with YAML.
+```
+
+## Contents
+
+- [Key-Value Pairs](#key-value-pairs)
+- [Comments](#comments)
+- [Maps](#maps)
+- [Arrays](#arrays)
+- [JSON Style](#json-style)
+
+## Key-Value Pairs
+
+Fundamentally, a file written in YAML consists of a set of _key-value pairs_.
+Each pair is written as `key: value`,
+where whitespace after the `:` is required.
+Key names in CWL files should not contain whitespace -
+[_camelCase_][camelCase] is used for multi-word key names
+that have special meaning in the CWL specification
+and underscored key names otherwise.
+For example:
+
+```yaml
+first_name: Bilbo
+last_name: Baggins
+age_years: 111
+home: Bag End, Hobbiton
+```
+
+The YAML above defines four keys -
+`first_name`, `last_name`, `age_years`, and `home` -
+with their four respective values.
+Values can be
+character strings,
+numeric (integer, floating point, or scientific representation),
+Boolean (`true` or `false`),
+or more complex nested types (see below).
+
+Values may be wrapped in quotation marks,
+but be aware that this may change the way that they are interpreted
+i.e. `"1234"` will be treated as a character string
+, while `1234` will be treated as an integer.
+This distinction can be important,
+for example when describing parameters to a command:
+in CWL all parts of `baseCommand` must be strings so,
+if you want to specify a fixed numeric value to a command,
+make sure that you wrap that numeric value in quotes: `baseCommand: [echo, "42"]`.
+
+## Comments
+
+You may use `#` to add comments to your CWL and parameter files.
+Any characters to the right of ` #` will be ignored by the program interpreting
+the YAML.
+For example:
+
+```yaml
+first_name: Bilbo
+last_name: Baggins
+age_years: 111
+# this line will be ignored by the interpreter
+home: Bag End, Hobbiton # this is ignored too
+```
+
+If there is anything on the line before the comment,
+be sure to add at least one space before the `#`!
+
+## Maps
+
+When describing a tool or workflow with CWL,
+it is usually necessary to construct more complex, nested representations.
+Referred to as _maps_,
+these hierarchical structures are described in YAML by providing
+additional key-value pairs as the value of any key.
+These pairs (sometimes referred to as "children") are written
+on new lines under the key to which they belong (the "parent"),
+and should be indented with two spaces
+(⇥tab characters are not allowed).
+For example:
+
+```yaml
+cwlVersion: v1.0
+class: CommandLineTool
+baseCommand: echo
+inputs: # this key has an object value
+ example_flag: # so does this one
+ type: boolean
+ inputBinding: # and this one too
+ position: 1
+ prefix: -f
+```
+
+The YAML above illustrates how to build up complex nested object
+descriptions relatively quickly.
+The `inputs` map contains a single key, `example_flag`,
+which itself contains two keys, `type` and `inputBinding`,
+while one of these children, `inputBinding`,
+contains a further two key-value pairs (`position` and `prefix`).
+See the [Arrays](#arrays) section below for more information about providing multiple
+values/key-value pairs for a single key.
+For comparison with the example YAML above,
+here is a graphical representation of the `inputs` object it describes.
+
+
+graph TD
+ inputs --> example_flag
+ example_flag --> type
+ type --- bool((boolean))
+ example_flag --> inputBinding
+ inputBinding --> position
+ inputBinding --> prefix
+ position --- posval((1))
+ prefix --- prefval(('-f'))
+
+
+
+
+
+
+
+
+