search

common-workflow-language / user_guide

The CWL v1.0 - v1.2 user guide
http://www.commonwl.org/user_guide/
Other
42 stars 67 forks source link

Contradicting statements #177

Closed ktaletsk closed 3 years ago

ktaletsk commented 4 years ago

In the Chapter 13 of Tutorial (https://github.com/common-workflow-language/user_guide/blame/gh-pages/_episodes/13-expressions.md#L85-L87) it is stated that "requirements must be provided as an array, with each entry (in this case, only class: InlineJavascriptRequirement) marked by a -". However, in the provided example in that (and previous chapters) requirements are provided without dashes or "class" identifier:

requirements:
  InlineJavascriptRequirement: {}

I am confused with these two contradicting statements. Which one is correct?

tom-tan commented 4 years ago

In short, both are correct.

But I agree with that it is confusing for readers. It will be better to unify the syntax in the user guide or to add a description of preprocessing rules.

IMO, the former is an easier solution for it.

Here is a detailed explanation.

The CommandLineTool section in specification of CWL v1.1 describes the type of requirements field as follows:

array<InlineJavascriptRequirement | SchemaDefRequirement | ...> | 
map<class, InlineJavascriptRequirement | SchemaDefRequirement | ...>

Also, the section 2.2 shows some examples how it works and specification of SALAD describes more precise rules.

That is,

requirements:
  InlineJavascriptRequirement: {}

is equivalent to the following (from the user point of view):

requirements:
  - class: InlineJavascriptRequirement

The above preprocessing rules are same in CWL v1.0.

twigleingrid commented 3 years ago

I created a small fix for this documentation issue. Please take a look & review my PR: https://github.com/common-workflow-language/user_guide/pull/208