Update reference.rst

document manual capture of line magics

docs/source/interactive/reference.rst

@@ -145,6 +145,10 b' use it:'
 
     /home/fperez/ipython
 
+Line magics, if they return a value, can be assigned to a variable using the syntax
+``l = %sx ls`` (which returns the result of `ls` as a python list).  See :ref:`below <manual_capture>`
+for more information.
+
 Type ``%magic`` for more information, including a list of all available magic
 functions at any time and their docstrings. You can also type
 ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for
@@ -356,16 +360,22 b' Any input line beginning with a ! character is passed verbatim (minus'
 the !, of course) to the underlying operating system. For example,
 typing ``!ls`` will run 'ls' in the current directory.
 
-Manual capture of command output
---------------------------------
+.. _manual_capture:
 
-You can assign the result of a system command to a Python variable with the
-syntax ``myfiles = !ls``. This gets machine readable output from stdout 
-(e.g. without colours), and splits on newlines. To explicitly get this sort of
-output without assigning to a variable, use two exclamation marks (``!!ls``) or
-the :magic:`sx` magic command.
+Manual capture of command output and magic output
+-------------------------------------------------
 
-The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s``
+You can assign the result of a system command to a Python variable with the
+syntax ``myfiles = !ls``. Similarly, the result of a magic (as long as it returns
+a value) can be assigned to a variable.  For example, the syntax ``myfiles = %sx ls``
+is equivalent to the above system command example (the :magic:`sx` runs a shell command
+and captures the output).  Each of these gets machine 
+readable output from stdout (e.g. without colours), and splits on newlines. To 
+explicitly get this sort of output without assigning to a variable, use two 
+exclamation marks (``!!ls``) or the :magic:`sx` magic command without an assignment.
+(Note that ``!!`` commands cannot be assigned to a variable.)
+
+The captured list in this example has some convenience features. ``myfiles.n`` or ``myfiles.s``
 returns a string delimited by newlines or spaces, respectively. ``myfiles.p``
 produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items.
 See :ref:`string_lists` for details.