Clarify the document about the order of matryoshka shells

(nesting shells)

1 files changed, 20 insertions, 15 deletions

diff --git a/lib/ansible/plugins/connection/__init__.py b/lib/ansible/plugins/connection/__init__.py
index 315293163b..d884496368 100644
--- a/lib/ansible/plugins/connection/__init__.py
+++ b/lib/ansible/plugins/connection/__init__.py
@@ -173,8 +173,8 @@ class ConnectionBase(with_metaclass(ABCMeta, object)):
         When a command is executed, it goes through multiple commands to get
         there.  It looks approximately like this::
 
-            HardCodedShell ConnectionCommand UsersLoginShell DEFAULT_EXECUTABLE BecomeCommand DEFAULT_EXECUTABLE Command
-        :HardCodedShell: Is optional.  It is run locally to invoke the
+            [LocalShell] ConnectionCommand [UsersLoginShell (*)] DEFAULT_EXECUTABLE [(BecomeCommand DEFAULT_EXECUTABLE)] Command
+        :LocalShell: Is optional.  It is run locally to invoke the
             ``Connection Command``.  In most instances, the
             ``ConnectionCommand`` can be invoked directly instead.  The ssh
             connection plugin which can have values that need expanding
@@ -187,15 +187,17 @@ class ConnectionBase(with_metaclass(ABCMeta, object)):
             ``ansible_ssh_host`` and so forth are fed to this piece of the
             command to connect to the correct host (Examples ``ssh``,
             ``chroot``)
-        :UsersLoginShell: This is the shell that the ``ansible_ssh_user`` has
-            configured as their login shell.  In traditional UNIX parlance,
-            this is the last field of a user's ``/etc/passwd`` entry   We do not
-            specifically try to run the ``UsersLoginShell`` when we connect.
-            Instead it is implicit in the actions that the
-            ``ConnectionCommand`` takes when it connects to a remote machine.
-            ``ansible_shell_type`` may be set to inform ansible of differences
-            in how the ``UsersLoginShell`` handles things like quoting if a
-            shell has different semantics than the Bourne shell.
+        :UsersLoginShell: This shell may or may not be created depending on
+            the ConnectionCommand used by the connection plugin.  This is the
+            shell that the ``ansible_ssh_user`` has configured as their login
+            shell.  In traditional UNIX parlance, this is the last field of
+            a user's ``/etc/passwd`` entry   We do not specifically try to run
+            the ``UsersLoginShell`` when we connect.  Instead it is implicit
+            in the actions that the ``ConnectionCommand`` takes when it
+            connects to a remote machine.  ``ansible_shell_type`` may be set
+            to inform ansible of differences in how the ``UsersLoginShell``
+            handles things like quoting if a shell has different semantics
+            than the Bourne shell.
         :DEFAULT_EXECUTABLE: This is the shell accessible via
             ``ansible.constants.DEFAULT_EXECUTABLE``.  We explicitly invoke
             this shell so that we have predictable quoting rules at this
@@ -207,10 +209,13 @@ class ConnectionBase(with_metaclass(ABCMeta, object)):
             ``BecomeCommand``.  After the ConnectionCommand, this is run by
             the ``UsersLoginShell``.  After the ``BecomeCommand`` we specify
             that the ``DEFAULT_EXECUTABLE`` is being invoked directly.
-        :BecomeComand: Is the command that performs privilege escalation.
-            Setting this up is performed by the action plugin prior to running
-            ``exec_command``. So we just get passed :param:`cmd` which has the
-            BecomeCommand already added.  (Examples: sudo, su)
+        :BecomeComand DEFAULTEXECUTABLE: Is the command that performs
+            privilege escalation.  Setting this up is performed by the action
+            plugin prior to running ``exec_command``. So we just get passed
+            :param:`cmd` which has the BecomeCommand already added.
+            (Examples: sudo, su)  If we have a BecomeCommand then we will
+            invoke a DEFAULT_EXECUTABLE shell inside of it so that we have
+            a consistent view of quoting.
         :Command: Is the command we're actually trying to run remotely.
             (Examples: mkdir -p $HOME/.ansible, python $HOME/.ansible/tmp-script-file)
         """