15028: Reorganize CWL documentation some more

[arvados.git] / doc / user / cwl / cwl-extensions.html.textile.liquid

diff --git a/doc/user/cwl/cwl-extensions.html.textile.liquid b/doc/user/cwl/cwl-extensions.html.textile.liquid
index 847df78f20be4016e72494b4c2aa8b94ea7afcbc..d73e83ce0e679f8f0e6d072327bb229cc19a5ad2 100644 (file)
--- a/doc/user/cwl/cwl-extensions.html.textile.liquid
+++ b/doc/user/cwl/cwl-extensions.html.textile.liquid
@@ -19,7 +19,7 @@ $namespaces:
   cwltool: "http://commonwl.org/cwltool#"
 {% endcodeblock %}
 
-For portability, Arvados extensions should go into the @hints@ section of your CWL file, for example:
+For portability, most Arvados extensions should go into the @hints@ section of your CWL file.  This makes it possible for your workflows to run other CWL runners that do not recognize Arvados hints.  The difference between @hints@ and @requirements@ is that @hints@ are optional features that can be ignored by other runners and still produce the same output, whereas @requirements@ will fail the workflow if they cannot be fulfilled.  For example, @arv:IntermediateOutput@ should go in @hints@ as it will have no effect on non-Arvados platforms, however if your workflow explicitly accesses the Arvados API and will fail without it, you should put @arv:APIRequirement@ in @requirements@.
 
 {% codeblock as yaml %}
 hints:
@@ -49,8 +49,6 @@ hints:
     project_uuid: clsr1-j7d0g-qxc4jcji7n4lafx
 {% endcodeblock %}
 
-The one exception to the @hints@ section this is @arv:APIRequirement@, see note below.
-
 h2(#RunInSingleContainer). arv:RunInSingleContainer
 
 Apply this to a workflow step that runs a subworkflow.  Indicates that all the steps of the subworkflow should run together in a single container and not be scheduled separately.  If you have a sequence of short-running steps (less than 1-2 minutes each) this enables you to avoid scheduling and data transfer overhead by running all the steps together at once.  To use this feature, @cwltool@ must be installed in the container image.