updated docs to suggest quote filter for shells

Also changed comments into -name in examples where appropriate.

lib/ansible/modules/commands/command.py

@@ -71,30 +71,33 @@ options:
       - if command warnings are on in ansible.cfg, do not warn about this particular line if set to no/false.
     required: false
 notes:
-    -  If you want to run a command through the shell (say you are using C(<),
-       C(>), C(|), etc), you actually want the M(shell) module instead. The
-       M(command) module is much more secure as it's not affected by the user's
-       environment.
-    -  " C(creates), C(removes), and C(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this."
+    -  If you want to run a command through the shell (say you are using C(<), C(>), C(|), etc), you actually want the M(shell) module instead.
+       The M(command) module is much more secure as it's not affected by the user's environment.
+    -  " C(creates), C(removes), and C(chdir) can be specified after the command.
+       For instance, if you only want to run a command if a certain file does not exist, use this."
 author: 
     - Ansible Core Team
     - Michael DeHaan
 '''
 
 EXAMPLES = '''
-# Example from Ansible Playbooks.
-- command: /sbin/shutdown -t now
+- name: return motd to registered var
+  command: cat /etc/motd
+  register: mymotd
 
-# Run the command if the specified file does not exist.
-- command: /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database
+- name: Run the command if the specified file does not exist.
+  command: /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database
 
-# You can also use the 'args' form to provide the options. This command
-# will change the working directory to somedir/ and will only run when
-# /path/to/database doesn't exist.
-- command: /usr/bin/make_database.sh arg1 arg2
+# You can also use the 'args' form to provide the options.
+- name: This command will change the working directory to somedir/ and will only run when /path/to/database doesn't exist.
+  command: /usr/bin/make_database.sh arg1 arg2
   args:
     chdir: somedir/
     creates: /path/to/database
+
+- name: safely use tempalated variable to run command. Always use the quote filter to avoid injection issues.
+  command: cat {{ myfile|quote }}
+  register: myoutput
 '''
 
 import datetime

lib/ansible/modules/commands/raw.py

@@ -64,15 +64,17 @@ author:
 '''
 
 EXAMPLES = '''
-# Bootstrap a legacy python 2.4 host
-- raw: yum -y install python-simplejson
+- name: Bootstrap a legacy python 2.4 host
+  raw: yum -y install python-simplejson
 
-# Bootstrap a host without python2 installed
-- raw: dnf install -y python2 python2-dnf libselinux-python
+- name: Bootstrap a host without python2 installed
+  raw: dnf install -y python2 python2-dnf libselinux-python
 
-# Run a command that uses non-posix shell-isms (in this example /bin/sh
-# doesn't handle redirection and wildcards together but bash does)
-- raw: cat < /tmp/*txt
+- name: Run a command that uses non-posix shell-isms (in this example /bin/sh doesn't handle redirection and wildcards together but bash does)
+  raw: cat < /tmp/*txt
   args:
     executable: /bin/bash
+
+- name: safely use templated variables. Always use quote filter to avoid injection issues.
+  raw: {{package_mgr|quote}} {{pkg_flags|quote}} install {{python_simplejson|quote}}
 '''

lib/ansible/modules/commands/shell.py

@@ -82,28 +82,28 @@ author:
 '''
 
 EXAMPLES = '''
-# Execute the command in remote shell; stdout goes to the specified
-# file on the remote.
-- shell: somescript.sh >> somelog.txt
+- name: Execute the command in remote shell; stdout goes to the specified file on the remote.
+  shell: somescript.sh >> somelog.txt
 
-# Change the working directory to somedir/ before executing the command.
-- shell: somescript.sh >> somelog.txt
+- name: Change the working directory to somedir/ before executing the command.
+  shell: somescript.sh >> somelog.txt
   args:
     chdir: somedir/
 
-# You can also use the 'args' form to provide the options. This command
-# will change the working directory to somedir/ and will only run when
-# somedir/somelog.txt doesn't exist.
-- shell: somescript.sh >> somelog.txt
+# You can also use the 'args' form to provide the options.
+- name: This command will change the working directory to somedir/ and will only run when somedir/somelog.txt doesn't exist.
+  shell: somescript.sh >> somelog.txt
   args:
     chdir: somedir/
     creates: somelog.txt
 
-# Run a command that uses non-posix shell-isms (in this example /bin/sh
-# doesn't handle redirection and wildcards together but bash does)
-- shell: cat < /tmp/*txt
+- name: Run a command that uses non-posix shell-isms (in this example /bin/sh doesn't handle redirection and wildcards together but bash does)
+  shell: cat < /tmp/*txt
   args:
     executable: /bin/bash
+
+- name: Run a command using a templated variable (always use quote filter to avoid injection)
+  shell: cat {{ myfile|quote }}
 '''
 
 RETURN = '''