Updating documentation.

TUTORIAL.md

@@ -211,17 +211,27 @@ node {
 }
 ```
 
-(Note: you cannot run the above script in the Groovy sandbox until Workflow 1.1 or later.)
-
 Properties of this variable will be environment variables on the current node.
 You can also override certain environment variables, and the overrides will be seen by subsequent `sh` steps (or anything else that pays attention to environment variables).
 This is convenient because now we can run `mvn` without a fully-qualified path.
 
-We will not use this style again, for reasons that will be explained later in more complex examples.
+Setting a variable like `PATH` in this way is of course only safe if you are using a single slave for this build, so we will not do so below.
+As an alternative you can use the `withEnv` step to set a variable within a scope:
+
+```groovy
+node {
+  git url: 'https://github.com/jglick/simple-maven-project-with-tests.git'
+  withEnv(["PATH+MAVEN=${tool 'M3'}/bin"]) {
+    sh 'mvn -B verify'
+  }
+}
+```
 
 Some environment variables are defined by Jenkins by default, as for freestyle builds.
 For example, `env.BUILD_TAG` can be used to get a tag like `jenkins-projname-1` from Groovy code, or `$BUILD_TAG` can be used from a `sh` script.
 
+See the help in the _Snippet Generator_ for the `withEnv` step for more details on this topic.
+
 ## Build parameters
 
 If you have configured your workflow to accept parameters when it is built (_Build with Parameters_), these will be accessible as Groovy variables of the same name.
@@ -563,7 +573,7 @@ env.PATH = "${mvnHome}/bin:${env.PATH}"
 ```
 
 since environment variable overrides are currently limited to being global to a workflow run, not local to the current thread (and thus slave).
-You could however use the `withEnv` step (TODO details).
+You could however use the `withEnv` step as noted above.
 
 You may also have noticed that we are running `JUnitResultArchiver` several times, something that is not possible in a freestyle project.
 The test results recorded in the build are cumulative.

basic-steps/src/main/resources/org/jenkinsci/plugins/workflow/steps/EnvStep/help.html

@@ -1,37 +1,44 @@
 <div>
 Sets one or more environment variables within a block.
-This is a more robust way of setting variables than setting values of <code>env.NAME</code>.
-<p>A set of environment variables are made available to all Jenkins Job types, including Workflow Jobs.
-The following is a general list of variables (by name) that are available to all Job types. See the notes
-below the list for Workflow specific details.
+These are available to any external processes spawned within that scope.
+For example:
+<p><pre>
+node {
+  withEnv(['MYTOOL_HOME=/usr/local/mytool']) {
+    sh '$MYTOOL_HOME/bin/start'
+  }
+}
+</pre>
+<p>(Note that here we are using single quotes in Groovy, so the variable expansion is being done by the Bourne shell, not Jenkins.)
+<p>From Groovy code inside the block, the value is also accessible as <code>env.VARNAME</code>.
+You can write to this property rather than using the <code>withEnv</code> step,
+though any changes are global to the workflow build so should not include node-specific content such as file paths:
+<p><pre>
+env.MYTOOL_VERSION = '1.33'
+node {
+  sh '/usr/local/mytool-$MYTOOL_VERSION/bin/start'
+}
+</pre>
+<p>A set of environment variables are made available to all Jenkins projects, including workflows.
+The following is a general list of variables (by name) that are available;
+see the notes below the list for Workflow-specific details.
 
 <p>
     <iframe src="${rootURL}/env-vars.html" width="100%"></iframe>
 </p>
 
 The following variables are currently unavailable inside a workflow script:
 <ul>
-    <li>EXECUTOR_NUMBER</li>
-    <li>NODE_NAME</li>
-    <li>NODE_LABELS</li>
-    <li>WORKSPACE</li>
+    <li><code>EXECUTOR_NUMBER</code></li>
+    <li><code>NODE_NAME</code></li>
+    <li><code>NODE_LABELS</code></li>
+    <li><code>WORKSPACE</code></li>
+    <li>SCM-specific variables such as <code>SVN_REVISION</code><li>
 </ul>
-
-<h4>Using Environment Variables</h4>
-
-Environment variables are injected into scripts through a variable named "<strong>env</strong>". This variable,
-like any other variable, can be used in the general flow of the script, or in variable substitutions e.g. when
-constructing email content when using the <code>mail</code> step:
-
-<p/>
-<pre>
-    mail (to: '[email protected]',
-        subject: "Job '${env.JOB_NAME}' (${env.BUILD_NUMBER}) is waiting for input",
-        body: "Please go to ${env.BUILD_URL} and verify the build");
+As an example of loading variable values from Groovy:
+<p><pre>
+mail to: '[email protected]',
+    subject: "Job '${env.JOB_NAME}' (${env.BUILD_NUMBER}) is waiting for input",
+    body: "Please go to ${env.BUILD_URL} and verify the build"
 </pre>
-
-<p/>
-For more on environment variables,
-<a href="https://github.com/jenkinsci/workflow-plugin/blob/master/TUTORIAL.md#managing-the-environment" target="_blank">see
-here</a>.
 </div>