Update docs about autocall and remove manual copy of cmd-line flags.

A manual copy of all the flags kept in the docs will always grow
stale, so we might as well simply indicate to users how to get the
listing at runtime.  If there's real demand for having this in the
docs, then it should be auto-generated so at least it's up to date
with the code.

IPython/core/usage.py

@@ -195,6 +195,11 b' MAIN FEATURES'
             In [1]: callable_ob arg1, arg2, arg3
         and the input will be translated to this:
             ------> callable_ob(arg1, arg2, arg3)
+        This feature is off by default (in rare cases it can produce
+        undesirable side-effects), but you can activate it at the command-line
+        by starting IPython with `--autocall 1`, set it permanently in your
+        configuration file, or turn on at runtime with `%autocall 1`.
+
         You can force auto-parentheses by using '/' as the first character
         of a line.  For example:
             In [1]: /globals             # becomes 'globals()'
@@ -285,7 +290,7 b' _oh : Output history'
 
 Autocall:
 
-f 1,2            : f(1,2)
+f 1,2            : f(1,2)  # Off by default, enable with %autocall magic.
 /f 1,2           : f(1,2) (forced autoparen)
 ,f 1 2           : f("1","2")
 ;f 1 2           : f("1 2")

docs/source/interactive/reference.txt

@@ -44,289 +44,29 b' interface, or specify the gui at the commandline::'
     $ ipython --gui=qt
 
 
-Regular Options
----------------
+Command-line Options
+--------------------
+
+To see the options IPython accepts, use ``ipython --help`` (and you probably
+should run the output through a pager such as ``ipython --help | less`` for
+more convenient reading).  This shows all the options that have a single-word
+alias to control them, but IPython lets you configure all of its objects from
+the command-line by passing the full class name and a corresponding value; type
+``ipython --help-all`` to see this full list.  For example::
+
+  ipython --pylab qt
+
+is equivalent to::
+
+  ipython --TerminalIPythonApp.pylab='qt'
+
+Note that in the second form, you *must* use the equal sign, as the expression
+is evaluated as an actual Python assignment.  While in the above example the
+short form is more convenient, only the most common options have a short form,
+while any configurable variable in IPython can be set at the command-line by
+using the long form.  This long form is the same syntax used in the
+configuration files, if you want to set these options permanently.
 
-After the above threading options have been given, regular options can
-follow in any order. All options can be abbreviated to their shortest
-non-ambiguous form and are case-sensitive.
-
-Most options can also be set from your configuration file. See the provided
-example for more details on what the options do. Options given at the command
-line override the values set in the configuration 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.
-
-    ``--pylab, pylab=<name>``
-    See :ref:`Matplotlib support <matplotlib_support>`
-    for more details.
-
-    ``--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,
-	'1' for smart autocall, where it is not applied if there are no more
-	arguments on the line, and '2' for full autocall, where all callable
-	objects are automatically called (even if no arguments are
-	present). The default is '1'.
-
-    ``--[no-]autoindent``
-	Turn automatic indentation on/off.
-
-    ``--[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``
-	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).
-
-    ``-c <command>``
-	execute the given command string. This is similar to the -c
-	option in the normal Python interpreter.
-
-    ``--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,
-	and the minimum value accepted is 20 (if you provide a value less than
-	20, it is reset to 0 and a warning is issued) This limit is defined
-	because otherwise you'll spend more time re-flushing a too small cache
-	than working.
-
-    ``--classic``
-	Gives IPython a similar feel to the classic Python
-	prompt.
-
-    ``--colors=<scheme>``
-	Color scheme for prompts and exception reporting. Currently
-	implemented: NoColor, Linux and LightBG.
-
-    ``--[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
-	passed through a pager (like 'less') and many pagers get confused with
-	color codes, this option is off by default. You can test it and turn
-	it on permanently in your configuration file if it works for you. As a
-	reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
-	that in RedHat 7.2 doesn't.
-
-	Test it and turn it on permanently if it works with your
-	system. The magic function %color_info allows you to toggle this
-	interactively for testing.
-
-    ``--[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``
-	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
-	reload of modules whose code may have changed, which the default
-	reload() function does not.
-
-	When deep_reload is off, IPython will use the normal reload(),
-	but deep_reload will still be available as dreload(). This
-	feature is off by default [which means that you have both
-	normal reload() and dreload()].
-
-.. this isn't currently working
-..    ``--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).
-	Since this editor is invoked on the fly by IPython and is
-	meant for editing small code snippets, you may want to use a
-	small, lightweight editor here (in case your default EDITOR is
-	something like Emacs).
-
-    ``--ipython_dir=<name>``
-	name of your IPython configuration directory IPYTHON_DIR. This
-	can also be specified through the environment variable
-	IPYTHON_DIR.
-
-    ``--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
-      the logfile). With -logplay, IPython will try to reconstruct the
-      previous working environment in full, not just execute the commands in
-      the logfile.
-
-      When a session is restored, logging is automatically turned on
-      again with the name of the logfile it was invoked with (it is
-      read from the log header). So once you've turned logging on for
-      a session, you can quit IPython and reload it as many times as
-      you want and it will continue to log its history and restore
-      from the beginning every time.
-      
-      Caveats: there are limitations in this option. The history
-      variables _i*,_* and _dh don't get restored properly. In the
-      future we will try to implement full session saving by writing
-      and retrieving a 'snapshot' of the memory state of IPython. But
-      our first attempts failed because of inherent limitations of
-      Python's Pickle module, so this may have to wait.
-
-    ``--[no-]messages``
-	Print messages which IPython collects about its startup
-	process (default on).
-
-    ``--[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``
-	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>``
-
-	Select the IPython profile by name.
-    
-	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
-	: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:
-
-	1. $IPYTHON_DIR/profile_default : load basic things you always want.
-	2. $IPYTHON_DIR/profile_math : load (1) and basic math-related modules.
-	3. $IPYTHON_DIR/profile_numeric : load (1) and Numeric and plotting modules.
-
-	Since it is possible to create an endless loop by having
-	circular file inclusions, IPython will stop if it reaches 15
-	recursive inclusions.
-
-    ``PromptManager.in_template=<string>``
-
-	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.
-
-    ``PromptManager.in2_template=<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
-	continuation prompt aligned with your input prompt).  Default:
-	' .\D.:' (note three spaces at the start for alignment with
-	'In [\#]').
-
-    ``PromptManager.out_template=<string>``
-	String used for output prompts, also uses numbers like
-	in_template. Default: 'Out[\#]:'
-
-    ``--quick``
-        start in bare bones mode (no config file loaded).
-
-    ``config_file=<name>``
-	name of your IPython resource configuration file. Normally
-	IPython loads ipython_config.py (from current directory) or
-	IPYTHON_DIR/profile_default.
-
-	If the loading of your config file fails, IPython starts with
-	a bare bones configuration (no modules loaded at all).
-
-    ``--[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
-	X/Emacs in Python comint or shell buffers.
-
-	Note that X/Emacs 'eterm' buffers (opened with M-x term) support
-	IPython's readline and syntax coloring fine, only 'emacs' (M-x
-	shell and C-c !) buffers do not.
-
-    ``--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
-	printed.
-
-	The default value for this is 0, which means IPython will
-	auto-detect your screen size every time it needs to print certain
-	potentially long strings (this doesn't change the behavior of the
-	'print' keyword, it's only triggered internally). If for some
-	reason this isn't working well (it needs curses support), specify
-	it yourself. Otherwise don't change the default.
-
-    ``--TerminalInteractiveShell.separate_in=<string>``
-
-	separator before input prompts.
-	Default: '\n'
-
-    ``--TerminalInteractiveShell.separate_out=<string>``
-        separator before output prompts.
-        Default: nothing.
-
-    ``--TerminalInteractiveShell.separate_out2=<string>``
-	separator after output prompts.
-	Default: nothing.
-	For these three options, use the value 0 to specify no separator.
-
-    ``--nosep``
-	shorthand for setting the above separators to empty strings.
-	
-	Simply removes all input/output separators.
-
-    ``--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.
-
-    ``--xmode=<modename>``
-
-	Mode for exception reporting.
-
-	Valid modes: Plain, Context and Verbose.
-
-	* Plain: similar to python's normal traceback printing.
-	* Context: prints 5 lines of context source code around each
-	  line in the traceback.
-	* Verbose: similar to Context, but additionally prints the
-	  variables currently visible where the exception happened
-	  (shortening their strings if too long). This can potentially be
-	  very slow, if you happen to have a huge data structure whose
-	  string representation is complex to compute. Your computer may
-	  appear to freeze for a while with cpu usage at 100%. If this
-	  occurs, you can cancel the traceback with Ctrl-C (maybe hitting it
-	  more than once).
 
 Interactive use
 ===============