doc improvements

docs/guides.rst

@@ -16,4 +16,5 @@ Guides
     tutorial_subproc_strings
     tutorial_ptk
     bash_to_xsh
-    python_virtual_environments
+    subproc_types
+    python_virtual_environments

docs/subproc_types.rst

@@ -0,0 +1,46 @@
+.. _subproc_types:
+
+***********************
+Subprocess Types Tables
+***********************
+Xonsh has a few different ways to launch subprocesses, each with their own
+unique interface depending on your need. The following table is a quick reference
+for the different suprocesses. The collumns have the following meaning:
+
+:Type: The sytnax for an example subprocess ``cmd``.
+:Output: Whether the output is streamed to stdout/stderr.  If "captured", the output is
+    not streamed as the ``cmd`` runs. If "uncaptured", the output is streamed.
+:Returns: The type of the object returned by the subprocess executions. For example,
+    if you were to run ``p = $(cmd)``, the return column gives the type of ``p``.
+:Notes: Any comments about the subprocess.
+
+.. list-table::
+    :header-rows: 1
+    :align: center
+
+    * - Type
+      - Output
+      - Returns
+      - Notes
+    * - ``cmd``
+      - Uncaptured
+      - ``HiddenCommandPipeline``
+      - The same as ``![cmd]``
+    * - ``![cmd]``
+      - Uncaptured
+      - ``HiddenCommandPipeline``
+      -
+    * - ``$[cmd]``
+      - Uncaptured
+      - ``None``
+      -
+    * - ``!(cmd)``
+      - Captured
+      - ``CommandPipeline``
+      -
+    * - ``$(cmd)``
+      - Captured
+      - ``str``
+      - stdout is returned
+
+

docs/tutorial.rst

@@ -455,7 +455,7 @@ difference is that the subprocess's stdout passes directly through xonsh and
 to the screen.  The return value of ``$[]`` is always ``None``.
 
 In the following, we can see that the results of ``$[]`` are automatically
-printed, and the return value is not a string.
+printed, and that the return value is not a string.
 
 .. code-block:: xonshcon
 
@@ -465,10 +465,6 @@ printed, and the return value is not a string.
     >>> x is None
     True
 
-Previously when we automatically entered subprocess-mode, uncaptured
-subprocesses were used.  Thus ``ls -l`` and ``$[ls -l]`` are usually
-equivalent.
-
 The ``![]`` operator is similar to the ``!()`` in that it returns an object
 containing information about the result of executing the given command.
 However, its standard output and standard error streams are directed to the
@@ -1534,7 +1530,7 @@ or by invoking xonsh with its filename as an argument:
     adding files
     file0.txt file1.txt file2.txt file3.txt file4.txt test_script.sh
 
-xonsh scripts can also accept command line arguments and parameters. 
+xonsh scripts can also accept command line arguments and parameters.
 These arguments are made available to the script in two different ways:
 
 #. In either mode, as individual variables ``$ARG<n>`` (e.g., ``$ARG1``)

docs/tutorial_subproc_strings.rst

@@ -17,7 +17,7 @@ Xonsh strings are exactly like Python strings everywhere. Xonsh uses
 exactly the same escape characters that Python does; no more and no less.
 This is different from other shells, which have a different set of escape
 sequences than Python has.  Notably, many sh-langs allow you to escape
-spaces with ``\ `` (backslash-space).
+spaces with ``"\ "`` (backslash-space).
 
 **bash**
 
@@ -32,7 +32,7 @@ to try this in xonsh, you'd see:
 
 **xonsh**
 
-.. code-block:: xonsh
+.. code-block:: xonshcon
 
     $ echo Actually\ Three\ Arguments
     Actually\ Three\ Arguments
@@ -43,7 +43,7 @@ pass in a single argument:
 
 **xonsh** or **bash**
 
-.. code-block:: xonsh
+.. code-block:: xonshcon
 
     $ echo "A Single Argument"
     A Single Argument
@@ -71,7 +71,7 @@ For example,
 
 **xonsh**
 
-.. code-block:: xonsh
+.. code-block:: xonshcon
 
     $ echo! A  Single     Argument
     A  Single     Argument
@@ -97,7 +97,7 @@ when leading and trailing quotes are not matched.
 
 **xonsh**
 
-.. code-block:: xonsh
+.. code-block:: xonshcon
 
     $ echo foo"bar"baz
     foo"bar"baz
@@ -110,7 +110,7 @@ You can think of these being equivalent to,
 
 **xonsh**
 
-.. code-block:: xonsh
+.. code-block:: xonshcon
 
     $ echo 'foo"bar"baz'
     foo"bar"baz