Merge pull request #22736 from bemeyert/21840-improve_cmd.run_env_docs

improve cmd.run env documentation

doc/man/salt.7

@@ -138136,8 +138136,8 @@ Example:
 .sp
 .nf
 .ft C
-salt://scripts/foo.sh:
-  cmd.script:
+foo-script:
+  cmd.run:
     \- env:
       \- BATCH: \(aqyes\(aq
 .ft P
@@ -138155,6 +138155,19 @@ quotes to be used as strings. More info on this (and other) PyYAML
 idiosyncrasies can be found \fBhere\fP\&.
 .UNINDENT
 .UNINDENT
+.sp
+Variables as values are not evaluated. So $PATH in the following example is a
+literal '$PATH':
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+bar-script:
+  cmd.run:
+    - env: "PATH=/some/path:$PATH"
+.UNINDENT
+.UNINDENT
 .TP
 .B stateful
 The command being executed is expected to return data about executing
@@ -138286,6 +138299,19 @@ quotes to be used as strings. More info on this (and other) PyYAML
 idiosyncrasies can be found \fBhere\fP\&.
 .UNINDENT
 .UNINDENT
+.sp
+Variables as values are not evaluated. So $PATH in the following example is a
+literal '$PATH':
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ salt://scripts/bar.sh:
+  cmd.script:
+    - env: "PATH=/some/path:$PATH"
+.UNINDENT
+.UNINDENT
 .TP
 .B umask
 The umask (in octal) to use when running the command.
@@ -138360,8 +138386,8 @@ Example:
 .sp
 .nf
 .ft C
-salt://scripts/foo.sh:
-  cmd.script:
+script-foo:
+  cmd.wait:
     \- env:
       \- BATCH: \(aqyes\(aq
 .ft P
@@ -138379,6 +138405,19 @@ quotes to be used as strings. More info on this (and other) PyYAML
 idiosyncrasies can be found \fBhere\fP\&.
 .UNINDENT
 .UNINDENT
+.sp
+Variables as values are not evaluated. So $PATH in the following example is a
+literal '$PATH':
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+script-bar:
+  cmd.wait:
+    - env: "PATH=/some/path:$PATH"
+.UNINDENT
+.UNINDENT
 .TP
 .B umask
 The umask (in octal) to use when running the command.
@@ -138460,7 +138499,7 @@ Example:
 .nf
 .ft C
 salt://scripts/foo.sh:
-  cmd.script:
+  cmd.wait_script:
     \- env:
       \- BATCH: \(aqyes\(aq
 .ft P
@@ -138478,6 +138517,19 @@ quotes to be used as strings. More info on this (and other) PyYAML
 idiosyncrasies can be found \fBhere\fP\&.
 .UNINDENT
 .UNINDENT
+.sp
+Variables as values are not evaluated. So $PATH in the following example is a
+literal '$PATH':
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ salt://scripts/bar.sh:
+  cmd.wait_script:
+    - env: "PATH=/some/path:$PATH"
+.UNINDENT
+.UNINDENT
 .TP
 .B umask
 The umask (in octal) to use when running the command.

salt/states/cmd.py

@@ -428,8 +428,8 @@ def wait(name,
 
         .. code-block:: yaml
 
-            salt://scripts/foo.sh:
-              cmd.script:
+            script-foo:
+              cmd.wait:
                 - env:
                   - BATCH: 'yes'
 
@@ -442,6 +442,15 @@ def wait(name,
             idiosyncrasies can be found :doc:`here
             </topics/troubleshooting/yaml_idiosyncrasies>`.
 
+        Variables as values are not evaluated. So $PATH in the following
+        example is a literal '$PATH':
+
+        .. code-block:: yaml
+
+            script-bar:
+              cmd.wait:
+                - env: "PATH=/some/path:$PATH"
+
     umask
          The umask (in octal) to use when running the command.
 
@@ -537,7 +546,7 @@ def wait_script(name,
         .. code-block:: yaml
 
             salt://scripts/foo.sh:
-              cmd.script:
+              cmd.wait_script:
                 - env:
                   - BATCH: 'yes'
 
@@ -550,6 +559,15 @@ def wait_script(name,
             idiosyncrasies can be found :doc:`here
             </topics/troubleshooting/yaml_idiosyncrasies>`.
 
+        Variables as values are not evaluated. So $PATH in the following
+        example is a literal '$PATH':
+
+        .. code-block:: yaml
+
+            salt://scripts/bar.sh:
+              cmd.wait_script:
+                - env: "PATH=/some/path:$PATH"
+
     umask
          The umask (in octal) to use when running the command.
 
@@ -626,8 +644,8 @@ def run(name,
 
         .. code-block:: yaml
 
-            salt://scripts/foo.sh:
-              cmd.script:
+            script-foo:
+              cmd.run:
                 - env:
                   - BATCH: 'yes'
 
@@ -640,6 +658,15 @@ def run(name,
             idiosyncrasies can be found :doc:`here
             </topics/troubleshooting/yaml_idiosyncrasies>`.
 
+        Variables as values are not evaluated. So $PATH in the following
+        example is a literal '$PATH':
+
+        .. code-block:: yaml
+
+            script-bar:
+              cmd.run:
+                - env: "PATH=/some/path:$PATH"
+
     stateful
         The command being executed is expected to return data about executing
         a state
@@ -845,6 +872,15 @@ def script(name,
             idiosyncrasies can be found :doc:`here
             </topics/troubleshooting/yaml_idiosyncrasies>`.
 
+        Variables as values are not evaluated. So $PATH in the following
+        example is a literal '$PATH':
+
+        .. code-block:: yaml
+
+            salt://scripts/bar.sh:
+              cmd.script:
+                - env: "PATH=/some/path:$PATH"
+
     umask
          The umask (in octal) to use when running the command.