general cleanup of interactive reference doc

docs/source/interactive/reference.txt

@@ -34,10 +34,8 b' $HOME/.ipython. For Windows users, $HOME resolves to C:\\\\Documents and'
 Settings\\YourUserName in most instances.
 
 
-
-
-Special Threading Options
--------------------------
+Eventloop integration
+---------------------
 
 Previously IPython had command line options for controlling GUI event loop
 integration (-gthread, -qthread, -q4thread, -wthread, -pylab). As of IPython
@@ -63,13 +61,13 b' given at the command line override the values set in the ipythonrc file.'
 All options with a [no] prepended can be specified in negated form
 (--no-option instead of --option) to turn the feature off.
 
-    -h, --help  print a help message and exit.
+    ``-h, --help``  print a help message and exit.
 
-    --pylab, pylab=<name>
+    ``--pylab, pylab=<name>``
     See :ref:`Matplotlib support <matplotlib_support>`
     for more details.
 
-    autocall=<val>
+    ``autocall=<val>``
 	Make IPython automatically call any callable object even if you
 	didn't type explicit parentheses. For example, 'str 43' becomes
 	'str(43)' automatically. The value can be '0' to disable the feature,
@@ -78,25 +76,26 b' All options with a [no] prepended can be specified in negated form'
 	objects are automatically called (even if no arguments are
 	present). The default is '1'.
 
-    --[no-]autoindent    
+    ``--[no-]autoindent``
 	Turn automatic indentation on/off.
 
-    --[no-]automagic 
+    ``--[no-]automagic``
 	make magic commands automatic (without needing their first character
 	to be %). Type %magic at the IPython prompt for more information.
 
-    --[no-]autoedit_syntax 
+    ``--[no-]autoedit_syntax``
 	When a syntax error occurs after editing a file, automatically
 	open the file to the trouble causing line for convenient
 	fixing.
 
-    --[no-]banner		Print the initial information banner (default on).
+    ``--[no-]banner``
+	Print the initial information banner (default on).
 
-    c=<command>
+    ``c=<command>``
 	execute the given command string. This is similar to the -c
 	option in the normal Python interpreter.
 
-    cache_size=<n> 
+    ``cache_size=<n>``
 	size of the output cache (maximum number of entries to hold in
 	memory). The default is 1000, you can change it permanently in your
 	config file. Setting it to 0 completely disables the caching system,
@@ -105,15 +104,15 b' All options with a [no] prepended can be specified in negated form'
 	because otherwise you'll spend more time re-flushing a too small cache
 	than working.
 
-    --classic
+    ``--classic``
 	Gives IPython a similar feel to the classic Python
 	prompt.
 
-    colors=<scheme> 
+    ``colors=<scheme>``
 	Color scheme for prompts and exception reporting. Currently
 	implemented: NoColor, Linux and LightBG.
 
-    --[no-]color_info 
+    ``--[no-]color_info``
 	IPython can display information about objects via a set of functions,
 	and optionally can use colors for this, syntax highlighting source
 	code and various other elements.  However, because this information is
@@ -127,12 +126,12 b' All options with a [no] prepended can be specified in negated form'
 	system. The magic function %color_info allows you to toggle this
 	interactively for testing.
 
-    --[no-]debug 
+    ``--[no-]debug``
 	Show information about the loading process. Very useful to pin down
 	problems with your configuration files or to get details about
 	session restores.
 
-    --[no-]deep_reload: 
+    ``--[no-]deep_reload``
 	IPython can use the deep_reload module which reloads changes in
 	modules recursively (it replaces the reload() function, so you don't
 	need to change anything to use it).  deep_reload() forces a full
@@ -144,7 +143,7 b' All options with a [no] prepended can be specified in negated form'
 	feature is off by default [which means that you have both
 	normal reload() and dreload()].
 
-    editor=<name>
+    ``editor=<name>``
 	Which editor to use with the %edit command. By default,
 	IPython will honor your EDITOR environment variable (if not
 	set, vi is the Unix default and notepad the Windows one).
@@ -153,22 +152,25 b' All options with a [no] prepended can be specified in negated form'
 	small, lightweight editor here (in case your default EDITOR is
 	something like Emacs).
 
-    ipython_dir=<name> 
+    ``ipython_dir=<name>``
 	name of your IPython configuration directory IPYTHON_DIR. This
 	can also be specified through the environment variable
 	IPYTHON_DIR.
 
-    -log, l 
-	generate a log file of all input. The file is named
-	ipython_log.py in your current directory (which prevents logs
-	from multiple IPython sessions from trampling each other). You
-	can use this to later restore a session by loading your
-	logfile as a file to be executed with option -logplay (see
-	below).
-
-    logfile=<name>   specify the name of your logfile.
-
-    logplay=<name> 
+    ``logfile=<name>``
+        specify the name of your logfile.
+        
+        This implies ``%logstart`` at the beginning of your session
+        
+        generate a log file of all input. The file is named
+        ipython_log.py in your current directory (which prevents logs
+        from multiple IPython sessions from trampling each other). You
+        can use this to later restore a session by loading your
+        logfile with ``ipython --i ipython_log.py``
+
+    ``logplay=<name>``
+    
+      NOT AVAILABLE in 0.11
 
       you can replay a previous log. For restoring a session as close as
       possible to the state you left it in, use this option (don't just run
@@ -190,31 +192,32 b' All options with a [no] prepended can be specified in negated form'
       our first attempts failed because of inherent limitations of
       Python's Pickle module, so this may have to wait.
 
-    --[no-]messages   
+    ``--[no-]messages``
 	Print messages which IPython collects about its startup
 	process (default on).
 
-    --[no-]pdb
+    ``--[no-]pdb``
 	Automatically call the pdb debugger after every uncaught
 	exception. If you are used to debugging using pdb, this puts
 	you automatically inside of it after any call (either in
 	IPython or in code called by it) which triggers an exception
 	which goes uncaught.
 
-    --[no-]pprint
+    ``--[no-]pprint``
 	ipython can optionally use the pprint (pretty printer) module
 	for displaying results. pprint tends to give a nicer display
 	of nested data structures. If you like it, you can turn it on
 	permanently in your config file (default off).
 
-    profile=<name>
+    ``profile=<name>``
 
-    Select the IPython profile by name.  
+	Select the IPython profile by name.
     
-    This is a quick way to keep and load multiple
+	This is a quick way to keep and load multiple
 	config files for different tasks, especially if you use the
 	include option of config files. You can keep a basic
-	IPYTHON_DIR/ipythonrc file and then have other 'profiles' which
+	:file:`IPYTHON_DIR/profile_default/ipython_config.py` file 
+	and then have other 'profiles' which
 	include this one and load extra things for particular
 	tasks. For example:
 
@@ -226,16 +229,16 b' All options with a [no] prepended can be specified in negated form'
 	circular file inclusions, IPython will stop if it reaches 15
 	recursive inclusions.
 
-    InteractiveShell.prompt_in1=<string>
+    ``InteractiveShell.prompt_in1=<string>``
 
-        Specify the string used for input prompts. Note that if you are using
+	Specify the string used for input prompts. Note that if you are using
 	numbered prompts, the number is represented with a '\#' in the
 	string. Don't forget to quote strings with spaces embedded in
 	them. Default: 'In [\#]:'.  The :ref:`prompts section <prompts>`
 	discusses in detail all the available escapes to customize your
 	prompts.
 
-    InteractiveShell.prompt_in2=<string>
+    ``InteractiveShell.prompt_in2=<string>``
 	Similar to the previous option, but used for the continuation
 	prompts. The special sequence '\D' is similar to '\#', but
 	with all digits replaced dots (so you can have your
@@ -243,14 +246,14 b' All options with a [no] prepended can be specified in negated form'
 	' .\D.:' (note three spaces at the start for alignment with
 	'In [\#]').
 
-    InteractiveShell.prompt_out=<string> 
+    ``InteractiveShell.prompt_out=<string>``
 	String used for output prompts, also uses numbers like
 	prompt_in1. Default: 'Out[\#]:'
 
-    --quick
-    start in bare bones mode (no config file loaded).
+    ``--quick``
+        start in bare bones mode (no config file loaded).
 
-    config_file=<name>   
+    ``config_file=<name>``
 	name of your IPython resource configuration file. Normally
 	IPython loads ipython_config.py (from current directory) or
 	IPYTHON_DIR/profile_default.
@@ -258,7 +261,7 b' All options with a [no] prepended can be specified in negated form'
 	If the loading of your config file fails, IPython starts with
 	a bare bones configuration (no modules loaded at all).
 
-    --[no-]readline
+    ``--[no-]readline``
 	use the readline library, which is needed to support name
 	completion and command history, among other things.  It is
 	enabled by default, but may cause problems for users of
@@ -268,7 +271,7 b' All options with a [no] prepended can be specified in negated form'
 	IPython's readline and syntax coloring fine, only 'emacs' (M-x
 	shell and C-c !) buffers do not.
 
-    TerminalInteractiveShell.screen_length=<n>
+    ``TerminalInteractiveShell.screen_length=<n>``
 	number of lines of your screen. This is used to control
 	printing of very long strings. Strings longer than this number
 	of lines will be sent through a pager instead of directly
@@ -281,35 +284,35 b' All options with a [no] prepended can be specified in negated form'
 	reason this isn't working well (it needs curses support), specify
 	it yourself. Otherwise don't change the default.
 
-    TerminalInteractiveShell.separate_in=<string>
+    ``TerminalInteractiveShell.separate_in=<string>``
 
 	separator before input prompts.
 	Default: '\n'
 
-    TerminalInteractiveShell.separate_out=<string>  
+    ``TerminalInteractiveShell.separate_out=<string>``
         separator before output prompts.
         Default: nothing.
 
-    TerminalInteractiveShell.separate_out2=<string>
+    ``TerminalInteractiveShell.separate_out2=<string>``
 	separator after output prompts.
 	Default: nothing.
 	For these three options, use the value 0 to specify no separator.
 
-    --nosep
+    ``--nosep``
 	shorthand for setting the above separators to empty strings.
 	
 	Simply removes all input/output separators.
 
-    --init
+    ``--init``
 	allows you to initialize a profile dir for configuration when you
 	install a new version of IPython or want to use a new profile.
 	Since new versions may include new command line options or example
 	files, this copies updated config files. Note that you should probably
 	use %upgrade instead,it's a safer alternative.
 
-    --version    print version information and exit.
+    ``--version``    print version information and exit.
 
-    xmode=<modename>
+    ``xmode=<modename>``
 
 	Mode for exception reporting.
 
@@ -557,11 +560,13 b' Note that there are 4 spaces between the quote marks after "M-i" above.'
 
 .. warning::
 
-    This feature is ON by default, but it can cause problems with
+    Autoindent is ON by default, but it can cause problems with
     the pasting of multi-line indented code (the pasted code gets
     re-indented on each line). A magic function %autoindent allows you to
     toggle it on/off at runtime. You can also disable it permanently on in
     your :file:`ipython_config.py` file (set TerminalInteractiveShell.autoindent=False).
+    
+    If you want to paste multiple lines, it is recommended that you use ``%paste``.
 
 
 Customizing readline behavior
@@ -607,10 +612,10 b' Session logging and restoring'
 -----------------------------
 
 You can log all input from a session either by starting IPython with the
-command line switches -log or -logfile (see :ref:`here <command_line_options>`)
+command line switche ``logfile=foo.py`` (see :ref:`here <command_line_options>`)
 or by activating the logging at any moment with the magic function %logstart.
 
-Log files can later be reloaded with the -logplay option and IPython
+Log files can later be reloaded by running them as scripts and IPython
 will attempt to 'replay' the log by executing all the lines in it, thus
 restoring the state of a previous session. This feature is not quite
 perfect, but can still be useful in many cases.
@@ -625,8 +630,8 b' follows:'
 
 %logstart [log_name [log_mode]]
 
-If no name is given, it defaults to a file named 'log' in your
-IPYTHON_DIR directory, in 'rotate' mode (see below).
+If no name is given, it defaults to a file named 'ipython_log.py' in your
+current working directory, in 'rotate' mode (see below).
 
 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
 history up to that point and then continues logging.
@@ -878,7 +883,7 b' Directory history'
 Your history of visited directories is kept in the global list _dh, and
 the magic %cd command can be used to go to any entry in that list. The
 %dhist command allows you to view this history. Do ``cd -<TAB`` to
-conventiently view the directory history.
+conveniently view the directory history.
 
 
 Automatic parentheses and quotes