From 0eb4abfca9127ad1a7a8153840f876e512c624cb Mon Sep 17 00:00:00 2001
From: Peter Amstutz <peter.amstutz@curoverse.com>
Date: Thu, 2 Oct 2014 17:11:23 -0400
Subject: [PATCH] 4042: Getting started on run-command reference

---
 ...id => _run_command_foreach_example.liquid} |  1 -
 .../_run_command_simple_example.liquid        | 25 +++++++++++++
 .../topics/run-command.html.textile.liquid    | 35 ++++++++++++++++---
 3 files changed, 55 insertions(+), 6 deletions(-)
 rename doc/_includes/{_run_command_example.liquid => _run_command_foreach_example.liquid} (93%)
 create mode 100644 doc/_includes/_run_command_simple_example.liquid

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 6de156d8c0..dfa14c954d 100644
--- 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
index 0000000000..dfa14c954d
--- /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 1a2616bbbf..85eefa8127 100644
--- 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>
-- 
2.30.2