4042: Getting started on run-command reference

diff --git a/doc/_includes/_run_command_example.liquid b/doc/_includes/_run_command_foreach_example.liquid
similarity index 93%
rename from doc/_includes/_run_command_example.liquid
rename to doc/_includes/_run_command_foreach_example.liquid
index 6de156d8c048dba6045114e31dcace50b8f0c6ba..dfa14c954dd5ff12e0c068a7df5db8525c174e60 100644 (file)
--- a/doc/_includes/_run_command_example.liquid
+++ b/doc/_includes/_run_command_foreach_example.liquid
@@ -12,7 +12,6 @@
             "$(glob $(dir $(sample))/*_1.fastq)",
             "$(glob $(dir $(sample))/*_2.fastq)"
         ],
-        "task.foreach": ["samples", "pairs"],
         "task.stdout": "$(basename $(glob $(dir $(sample))/*_1.fastq)).sam"
         "reference_collection": {
             "required": true,

diff --git a/doc/_includes/_run_command_simple_example.liquid b/doc/_includes/_run_command_simple_example.liquid
new file mode 100644 (file)
index 0000000..dfa14c9
--- /dev/null
+++ b/doc/_includes/_run_command_simple_example.liquid
@@ -0,0 +1,25 @@
+"bwa-mem": {
+    "script": "run-command",
+    "script_version": "master",
+    "repository": "arvados",
+    "script_parameters": {
+        "command": [
+            "bwa",
+            "mem",
+            "-t",
+            "$(node.cores)",
+            "$(glob $(dir $(reference_collection))/*.fasta)",
+            "$(glob $(dir $(sample))/*_1.fastq)",
+            "$(glob $(dir $(sample))/*_2.fastq)"
+        ],
+        "task.stdout": "$(basename $(glob $(dir $(sample))/*_1.fastq)).sam"
+        "reference_collection": {
+            "required": true,
+            "dataclass": "Collection"
+        },
+        "samples": {
+            "required": true,
+            "dataclass": "Collection"
+        },
+    }
+}

diff --git a/doc/user/topics/run-command.html.textile.liquid b/doc/user/topics/run-command.html.textile.liquid
index 1a2616bbbfb65e461ed0afad317811e9186363c9..85eefa8127de12fa187a0e4269997ad5bede4243 100644 (file)
--- a/doc/user/topics/run-command.html.textile.liquid
+++ b/doc/user/topics/run-command.html.textile.liquid
@@ -4,11 +4,36 @@ navsection: userguide
 title: "run-command reference"
 ...
 
-The @run-command@ crunch script provides a way to run a command over a dataset.  Run-command is controlled through the script_parameters section of a pipeline component.
+The @run-command@ crunch script enables you run command line programs.
 
-<notextile>{% code 'run_command_example' as javascript %}</notextile>
+h2. Basic usage
 
-The script_parameters section consists of three parts:
-* The @command@ section defining how to build the command line of task
-* Special processing directives @task.foreach@ @task.cwd@ @task.vwd@ @task.stdin@ @task.stdout@
+Run-command is controlled through the script_parameters section of a pipeline component.  The script_parameters of run-command section consists of three parts:
 * User-defined parameters
+* Special processing directives @task.foreach@ @task.cwd@ @task.vwd@ @task.stdin@ @task.stdout@
+* The @command@ section defines the template to actually build the command line of task
+
+h3. Parameter substitution
+
+Any entry in the "script_parameters" object that is not a directive or reserved parameter is a user-defined parameter.  User-defined parameters can be used in parameter substitution and in directives.  String substitution is indicated by wrapping the expression with @$(...)@.  In the following example, using @$(varA)@ for the value of "varB" denotes that it should be replaced with the value of the parameter "varA", which is "ABC".
+
+<pre>
+"script_parameters": {
+  "varA": "ABC",
+  "varB": "$(varA)"
+}
+</pre>
+
+
+
+h3. Directives
+
+h3. Command template
+
+The command section
+
+h2. Examples
+
+<notextile>{% code 'run_command_simple_example' as javascript %}</notextile>
+
+<notextile>{% code 'run_command_foreach_example' as javascript %}</notextile>