Unify command-line usage information in one place.

Fixes: https://bugs.launchpad.net/ipython/+bug/505047

IPython/core/application.py

@@ -51,26 +51,41 b' class ApplicationError(Exception):'
 
 
 app_cl_args = (
-        (('--ipython-dir', ), dict(
-            dest='Global.ipython_dir',type=unicode,
-            help='Set to override default location of Global.ipython_dir.',
-            default=NoConfigDefault,
-            metavar='Global.ipython_dir') ),
-        (('-p', '--profile',), dict(
-            dest='Global.profile',type=unicode,
-            help='The string name of the ipython profile to be used.',
-            default=NoConfigDefault,
-            metavar='Global.profile') ),
-        (('--log-level',), dict(
-            dest="Global.log_level",type=int,
-            help='Set the log level (0,10,20,30,40,50).  Default is 30.',
-            default=NoConfigDefault,
-            metavar='Global.log_level')),
-        (('--config-file',), dict(
-            dest='Global.config_file',type=unicode,
-            help='Set the config file name to override default.',
-            default=NoConfigDefault,
-            metavar='Global.config_file')),
+    (('--ipython-dir', ), dict(
+        dest='Global.ipython_dir',type=unicode,
+        help=
+        """Set to override default location of the IPython directory
+        IPYTHON_DIR, stored as Global.ipython_dir.  This can also be specified
+        through the environment variable IPYTHON_DIR.""",
+        default=NoConfigDefault,
+        metavar='Global.ipython_dir') ),
+    (('-p', '--profile',), dict(
+        dest='Global.profile',type=unicode,
+        help=
+        """The string name of the ipython profile to be used.  Assume that your
+        config file is ipython_config-<name>.py (looks in current dir first,
+        then in IPYTHON_DIR). This is a quick way to keep and load multiple
+        config files for different tasks, especially if include your basic one
+        in your more specialized ones.  You can keep a basic
+        IPYTHON_DIR/ipython_config.py file and then have other 'profiles' which
+        include this one and load extra things for particular tasks.""",
+        default=NoConfigDefault,
+        metavar='Global.profile') ),
+    (('--log-level',), dict(
+        dest="Global.log_level",type=int,
+        help='Set the log level (0,10,20,30,40,50).  Default is 30.',
+        default=NoConfigDefault,
+        metavar='Global.log_level')),
+    (('--config-file',), dict(
+        dest='Global.config_file',type=unicode,
+        help=
+        """Set the config file name to override default.  Normally IPython
+        loads ipython_config.py (from current directory) or
+        IPYTHON_DIR/ipython_config.py.  If the loading of your config file
+        fails, IPython starts with a bare bones configuration (no modules
+        loaded at all).""",
+        default=NoConfigDefault,
+        metavar='Global.config_file')),
     )
 
 class Application(object):
@@ -78,7 +93,8 b' class Application(object):'
 
     name = u'ipython'
     description = 'IPython: an enhanced interactive Python shell.'
-
+    #: usage message printed by argparse. If None, auto-generate
+    usage = None
     config_file_name = u'ipython_config.py'
     # Track the default and actual separately because some messages are
     # only printed if we aren't using the default.
@@ -199,7 +215,9 b' class Application(object):'
         """Create and return a command line config loader."""
         return ArgParseConfigLoader(self.argv, self.cl_arguments,
                                     description=self.description, 
-                                    version=release.version)
+                                    version=release.version,
+                                    usage=self.usage,
+                                    )
 
     def pre_load_command_line_config(self):
         """Do actions just before loading the command line config."""

IPython/core/ipapp.py

@@ -4,17 +4,15 b''
 The :class:`~IPython.core.application.Application` object for the command
 line :command:`ipython` program.
 
-Authors:
+Authors
+-------
 
 * Brian Granger
 * Fernando Perez
-
-Notes
------
 """
 
 #-----------------------------------------------------------------------------
-#  Copyright (C) 2008-2009  The IPython Development Team
+#  Copyright (C) 2008-2010  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
@@ -23,6 +21,7 b' Notes'
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
+from __future__ import absolute_import
 
 import logging
 import os
@@ -41,62 +40,78 b' from IPython.config.loader import ('
 )
 from IPython.lib import inputhook
 from IPython.utils.genutils import filefind, get_ipython_dir
+from . import usage
 
 #-----------------------------------------------------------------------------
-# Utilities and helpers
+# Globals, utilities and helpers
 #-----------------------------------------------------------------------------
 
-ipython_desc = """
-A Python shell with automatic history (input and output), dynamic object
-introspection, easier configuration, command completion, access to the system
-shell and more.
-"""
-
-#-----------------------------------------------------------------------------
-# Main classes and functions
-#-----------------------------------------------------------------------------
+default_config_file_name = u'ipython_config.py'
 
 cl_args = (
     (('--autocall',), dict(
         type=int, dest='InteractiveShell.autocall', default=NoConfigDefault,
-        help='Set the autocall value (0,1,2).',
+        help=
+        """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'.""",
         metavar='InteractiveShell.autocall')
     ),
     (('--autoindent',), dict(
-        action='store_true', dest='InteractiveShell.autoindent', default=NoConfigDefault,
+        action='store_true', dest='InteractiveShell.autoindent',
+        default=NoConfigDefault, 
         help='Turn on autoindenting.')
     ),
     (('--no-autoindent',), dict(
-        action='store_false', dest='InteractiveShell.autoindent', default=NoConfigDefault,
+        action='store_false', dest='InteractiveShell.autoindent',
+        default=NoConfigDefault, 
         help='Turn off autoindenting.')
     ),
     (('--automagic',), dict(
-        action='store_true', dest='InteractiveShell.automagic', default=NoConfigDefault,
-        help='Turn on the auto calling of magic commands.')
-    ),
+        action='store_true', dest='InteractiveShell.automagic',
+        default=NoConfigDefault, 
+        help='Turn on the auto calling of magic commands.'
+        'Type %%magic at  the  IPython  prompt  for  more information.')
+     ),
     (('--no-automagic',), dict(
-        action='store_false', dest='InteractiveShell.automagic', default=NoConfigDefault,
+        action='store_false', dest='InteractiveShell.automagic',
+        default=NoConfigDefault, 
         help='Turn off the auto calling of magic commands.')
     ),
     (('--autoedit-syntax',), dict(
-        action='store_true', dest='InteractiveShell.autoedit_syntax', default=NoConfigDefault,
+        action='store_true', dest='InteractiveShell.autoedit_syntax',
+        default=NoConfigDefault, 
         help='Turn on auto editing of files with syntax errors.')
     ),
     (('--no-autoedit-syntax',), dict(
-        action='store_false', dest='InteractiveShell.autoedit_syntax', default=NoConfigDefault,
+        action='store_false', dest='InteractiveShell.autoedit_syntax',
+        default=NoConfigDefault, 
         help='Turn off auto editing of files with syntax errors.')
     ),
     (('--banner',), dict(
-        action='store_true', dest='Global.display_banner', default=NoConfigDefault,
+        action='store_true', dest='Global.display_banner',
+        default=NoConfigDefault, 
         help='Display a banner upon starting IPython.')
     ),
     (('--no-banner',), dict(
-        action='store_false', dest='Global.display_banner', default=NoConfigDefault,
+        action='store_false', dest='Global.display_banner',
+        default=NoConfigDefault, 
         help="Don't display a banner upon starting IPython.")
     ),
     (('--cache-size',), dict(
         type=int, dest='InteractiveShell.cache_size', default=NoConfigDefault,
-        help="Set the size of the output cache.",
+        help=
+        """Set the size of the output cache.  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.
+        """,
         metavar='InteractiveShell.cache_size')
     ),
     (('--classic',), dict(
@@ -109,27 +124,57 b' cl_args = ('
         metavar='InteractiveShell.colors')
     ),
     (('--color-info',), dict(
-        action='store_true', dest='InteractiveShell.color_info', default=NoConfigDefault,
-        help="Enable using colors for info related things.")
+        action='store_true', dest='InteractiveShell.color_info',
+        default=NoConfigDefault, 
+        help=
+        """IPython can display information about objects via a set of func-
+        tions, 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 ipython_config.py file if it
+        works for you.  Test it and turn it on permanently if it works with
+        your system.  The magic function %%color_info allows you to toggle this
+        inter- actively for testing."""
+        )
     ),
     (('--no-color-info',), dict(
-        action='store_false', dest='InteractiveShell.color_info', default=NoConfigDefault,
+        action='store_false', dest='InteractiveShell.color_info',
+        default=NoConfigDefault, 
         help="Disable using colors for info related things.")
     ),
     (('--confirm-exit',), dict(
-        action='store_true', dest='InteractiveShell.confirm_exit', default=NoConfigDefault,
-        help="Prompt the user when existing.")
+        action='store_true', dest='InteractiveShell.confirm_exit',
+        default=NoConfigDefault, 
+        help=
+        """Set to confirm when you try to exit IPython with an EOF (Control-D
+        in Unix, Control-Z/Enter in Windows). By typing 'exit', 'quit' or
+        '%%Exit', you can force a direct exit without any confirmation.
+        """
+        )
     ),
     (('--no-confirm-exit',), dict(
-        action='store_false', dest='InteractiveShell.confirm_exit', default=NoConfigDefault,
-        help="Don't prompt the user when existing.")
+        action='store_false', dest='InteractiveShell.confirm_exit',
+        default=NoConfigDefault, 
+        help="Don't prompt the user when exiting.")
     ),
     (('--deep-reload',), dict(
-        action='store_true', dest='InteractiveShell.deep_reload', default=NoConfigDefault,
-        help="Enable deep (recursive) reloading by default.")
+        action='store_true', dest='InteractiveShell.deep_reload',
+        default=NoConfigDefault, 
+        help=
+        """Enable deep (recursive) reloading by default. 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 fea- ture is off
+        by default [which means that you have both normal reload() and
+        dreload()].""")
     ),
     (('--no-deep-reload',), dict(
-        action='store_false', dest='InteractiveShell.deep_reload', default=NoConfigDefault,
+        action='store_false', dest='InteractiveShell.deep_reload',
+        default=NoConfigDefault, 
         help="Disable deep (recursive) reloading by default.")
     ),
     (('--editor',), dict(
@@ -138,43 +183,62 b' cl_args = ('
         metavar='InteractiveShell.editor')
     ),
     (('--log','-l'), dict(
-        action='store_true', dest='InteractiveShell.logstart', default=NoConfigDefault,
-        help="Start logging to the default file (./ipython_log.py).")
+        action='store_true', dest='InteractiveShell.logstart',
+        default=NoConfigDefault, 
+        help="Start logging to the default log file (./ipython_log.py).")
     ),
     (('--logfile','-lf'), dict(
         type=unicode, dest='InteractiveShell.logfile', default=NoConfigDefault,
-        help="Start logging to logfile.",
+        help="Start logging to logfile with this name.",
         metavar='InteractiveShell.logfile')
     ),
     (('--log-append','-la'), dict(
-        type=unicode, dest='InteractiveShell.logappend', default=NoConfigDefault,
-        help="Start logging to the give file in append mode.",
+        type=unicode, dest='InteractiveShell.logappend',
+        default=NoConfigDefault, 
+        help="Start logging to the given file in append mode.",
         metavar='InteractiveShell.logfile')
     ),
     (('--pdb',), dict(
-        action='store_true', dest='InteractiveShell.pdb', default=NoConfigDefault,
+        action='store_true', dest='InteractiveShell.pdb',
+        default=NoConfigDefault, 
         help="Enable auto calling the pdb debugger after every exception.")
     ),
     (('--no-pdb',), dict(
-        action='store_false', dest='InteractiveShell.pdb', default=NoConfigDefault,
+        action='store_false', dest='InteractiveShell.pdb',
+        default=NoConfigDefault, 
         help="Disable auto calling the pdb debugger after every exception.")
     ),
     (('--pprint',), dict(
-        action='store_true', dest='InteractiveShell.pprint', default=NoConfigDefault,
+        action='store_true', dest='InteractiveShell.pprint',
+        default=NoConfigDefault, 
         help="Enable auto pretty printing of results.")
     ),
     (('--no-pprint',), dict(
-        action='store_false', dest='InteractiveShell.pprint', default=NoConfigDefault,
+        action='store_false', dest='InteractiveShell.pprint',
+        default=NoConfigDefault, 
         help="Disable auto auto pretty printing of results.")
     ),
     (('--prompt-in1','-pi1'), dict(
         type=str, dest='InteractiveShell.prompt_in1', default=NoConfigDefault,
-        help="Set the main input prompt ('In [\#]: ')",
+        help=
+        """Set the main input prompt ('In [\#]: ').  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. Most
+        bash-like escapes can be used to customize IPython's prompts, as well
+        as a few additional ones which are IPython-spe- cific.  All valid
+        prompt escapes are described in detail in the Customization section of
+        the IPython manual.""",
         metavar='InteractiveShell.prompt_in1')
     ),
     (('--prompt-in2','-pi2'), dict(
         type=str, dest='InteractiveShell.prompt_in2', default=NoConfigDefault,
-        help="Set the secondary input prompt (' .\D.: ')",
+        help=
+        """Set the secondary input prompt (' .\D.: ').  Similar to the previous
+        option, but used for the continuation prompts. The special sequence
+        '\D' is similar to '\#', but with all digits replaced by 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 [\#]')""",
         metavar='InteractiveShell.prompt_in2')
     ),
     (('--prompt-out','-po'), dict(
@@ -187,30 +251,44 b' cl_args = ('
         help="Enable quick startup with no config files.")
     ),
     (('--readline',), dict(
-        action='store_true', dest='InteractiveShell.readline_use', default=NoConfigDefault,
+        action='store_true', dest='InteractiveShell.readline_use',
+        default=NoConfigDefault, 
         help="Enable readline for command line usage.")
     ),
     (('--no-readline',), dict(
-        action='store_false', dest='InteractiveShell.readline_use', default=NoConfigDefault,
+        action='store_false', dest='InteractiveShell.readline_use',
+        default=NoConfigDefault, 
         help="Disable readline for command line usage.")
     ),
     (('--screen-length','-sl'), dict(
-        type=int, dest='InteractiveShell.screen_length', default=NoConfigDefault,
-        help='Number of lines on screen, used to control printing of long strings.',
+        type=int, dest='InteractiveShell.screen_length',
+        default=NoConfigDefault, 
+        help=
+        """Number of lines of your screen, 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.""",
         metavar='InteractiveShell.screen_length')
     ),
     (('--separate-in','-si'), dict(
         type=str, dest='InteractiveShell.separate_in', default=NoConfigDefault,
-        help="Separator before input prompts.  Default '\n'.",
+        help="Separator before input prompts.  Default '\\n'.",
         metavar='InteractiveShell.separate_in')
     ),
     (('--separate-out','-so'), dict(
-        type=str, dest='InteractiveShell.separate_out', default=NoConfigDefault,
+        type=str, dest='InteractiveShell.separate_out',
+        default=NoConfigDefault, 
         help="Separator before output prompts.  Default 0 (nothing).",
         metavar='InteractiveShell.separate_out')
     ),
     (('--separate-out2','-so2'), dict(
-        type=str, dest='InteractiveShell.separate_out2', default=NoConfigDefault,
+        type=str, dest='InteractiveShell.separate_out2',
+        default=NoConfigDefault, 
         help="Separator after output prompts.  Default 0 (nonight).",
         metavar='InteractiveShell.separate_out2')
     ),
@@ -219,16 +297,29 b' cl_args = ('
         help="Eliminate all spacing between prompts.")
     ),
     (('--term-title',), dict(
-        action='store_true', dest='InteractiveShell.term_title', default=NoConfigDefault,
+        action='store_true', dest='InteractiveShell.term_title',
+        default=NoConfigDefault, 
         help="Enable auto setting the terminal title.")
     ),
     (('--no-term-title',), dict(
-        action='store_false', dest='InteractiveShell.term_title', default=NoConfigDefault,
+        action='store_false', dest='InteractiveShell.term_title',
+        default=NoConfigDefault, 
         help="Disable auto setting the terminal title.")
     ),
     (('--xmode',), dict(
         type=str, dest='InteractiveShell.xmode', default=NoConfigDefault,
-        help="Exception mode ('Plain','Context','Verbose')",
+        help=
+        """Exception reporting mode ('Plain','Context','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).
+        """,
         metavar='InteractiveShell.xmode')
     ),
     (('--ext',), dict(
@@ -242,8 +333,11 b' cl_args = ('
         metavar='Global.code_to_run')
     ),
     (('-i',), dict(
-        action='store_true', dest='Global.force_interact', default=NoConfigDefault,
-        help="If running code from the command line, become interactive afterwards.")
+        action='store_true', dest='Global.force_interact',
+        default=NoConfigDefault, 
+        help=
+        "If running code from the command line, become interactive afterwards."
+        )
     ),
 
     # Options to start with GUI control enabled from the beginning
@@ -280,12 +374,17 b' cl_args = ('
     ),
 )
 
-
-default_config_file_name = u'ipython_config.py'
+#-----------------------------------------------------------------------------
+# Main classes and functions
+#-----------------------------------------------------------------------------
 
 class IPythonApp(Application):
     name = u'ipython'
-    description = 'IPython: an enhanced interactive Python shell.'
+    #: argparse formats better the 'usage' than the 'description' field
+    description = None
+    #: usage message printed by argparse. If None, auto-generate
+    usage = usage.cl_usage
+
     config_file_name = default_config_file_name
 
     cl_arguments = Application.cl_arguments + cl_args
@@ -309,7 +408,6 b' class IPythonApp(Application):'
         super(IPythonApp, self).__init__(argv)
         self.shell_params = shell_params
 
-
     def create_default_config(self):
         super(IPythonApp, self).create_default_config()
         # Eliminate multiple lookups

IPython/core/usage.py

@@ -1,338 +1,47 b''
 # -*- coding: utf-8 -*-
-#*****************************************************************************
-#       Copyright (C) 2001-2004 Fernando Perez. <[e-mail]>
+"""Usage information for the main IPython applications.
+"""
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2008-2010  The IPython Development Team
+#  Copyright (C) 2001-2007 Fernando Perez. <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
-#*****************************************************************************
+#-----------------------------------------------------------------------------
 
 import sys
 from IPython.core import release
 
-__doc__ = """
-IPython -- An enhanced Interactive Python
-=========================================
+cl_usage = """\
+ipython [options] [files]
 
-A Python shell with automatic history (input and output), dynamic object
-introspection, easier configuration, command completion, access to the system
-shell and more.
-
-IPython can also be embedded in running programs. See EMBEDDING below.
-
-
-USAGE
-       ipython [options] files
-
-       If invoked with no options, it executes all the files listed in
-       sequence and drops you into the interpreter while still acknowledging
-       any options you may have set in your ipythonrc file. This behavior is
-       different from standard Python, which when called as python -i will
-       only execute one file and will ignore your configuration setup.
-
-       Please note that some of the configuration options are not available at
-       the command line, simply because they are not practical here. Look into
-       your ipythonrc configuration file for details on those. This file
-       typically installed in the $HOME/.ipython directory.
-
-       For Windows users, $HOME resolves to C:\\Documents and
-       Settings\\YourUserName in most instances, and _ipython is used instead
-       of .ipython, since some Win32 programs have problems with dotted names
-       in directories.
-
-       In the rest of this text, we will refer to this directory as
-       IPYTHON_DIR.
-
-REGULAR OPTIONS
-       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.  One or two  dashes  can  be
-       used.   Some options have an alternate short form, indicated after a |.
-
-       Most options can also be set from your  ipythonrc  configuration  file.
-       See the provided examples for assistance.  Options given on the comman-
-       dline override the values set in the ipythonrc file.
-
-       All options with a [no] prepended can be specified in negated form
-       (using -nooption instead of -option) to turn the feature off.
-
-       -h, --help
-              Show summary of options.
-
-       -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 char-
-              acter 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 intial information banner (default on).
-
-       -c <command>
-              Execute  the  given  command  string, and set sys.argv to ['c'].
-              This is similar to the -c option in  the  normal  Python  inter-
-              preter.
-
-       -cache_size|cs <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|cl
-              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 func-
-              tions, and optionally can use colors for this, syntax highlight-
-              ing 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
-              ipythonrc 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 inter-
-              actively for testing.
-
-       -[no]confirm_exit
-              Set to confirm when you try to exit IPython with  an  EOF  (Con-
-              trol-D in Unix, Control-Z/Enter in Windows). Note that using the
-              magic functions @Exit or @Quit you  can  force  a  direct  exit,
-              bypassing any confirmation.
-
-       -[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  fea-
-              ture  is  off  by default [which means that you have both normal
-              reload() and dreload()].
-
-       -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).
-
-       -ipythondir <name>
-              The  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|lf
-              Specify the name of your logfile.
-
-       -logplay|lp
-              Replay  a previous log. For restoring a session as close as pos-
-              sible 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 vari-
-              ables  _i*,_* and _dh don't get restored properly. In the future
-              we will try to implement full  session  saving  by  writing  and
-              retrieving  a 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 excep-
-              tion. 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 per-
-              manently in your config file (default off).
-
-       -profile|p <name>
-              Assume that your config file is ipythonrc-<name> (looks in  cur-
-              rent dir first, then in IPYTHON_DIR). 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  include  this  one  and  load extra things for particular
-              tasks. For example:
-
-              1) $HOME/.ipython/ipythonrc : load basic things you always want.
-              2)  $HOME/.ipython/ipythonrc-math  :  load  (1)  and basic math-
-              related modules.
-              3) $HOME/.ipython/ipythonrc-numeric : load (1) and  Numeric  and
-              plotting modules.
-
-              Since  it is possible to create an endless loop by having circu-
-              lar file inclusions, IPython will stop if it reaches  15  recur-
-              sive inclusions.
-
-       -prompt_in1|pi1 <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 [\#]: '.
-
-              Most bash-like  escapes  can  be  used  to  customize  IPython's
-              prompts, as well as a few additional ones which are IPython-spe-
-              cific.  All valid prompt escapes are described in detail in  the
-              Customization section of the IPython HTML/PDF manual.
-
-       -prompt_in2|pi2 <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 [\#]').
-
-       -prompt_out|po <string>
-              String   used   for  output  prompts,  also  uses  numbers  like
-              prompt_in1.  Default: 'Out[\#]:'.
-
-       -quick Start in bare bones mode (no config file loaded).
-
-       -rcfile <name>
-              Name of your  IPython  resource  configuration  file.   normally
-              IPython    loads   ipythonrc   (from   current   directory)   or
-              IPYTHON_DIR/ipythonrc.  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  com-
-              pletion  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  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.
-
-       -screen_length|sl <n>
-              Number  of lines of your screen.  This is used to control print-
-              ing 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.
-
-       -separate_in|si <string>
-              Separator before input prompts.  Default '0.
-
-       -separate_out|so <string>
-              Separator before output prompts.  Default: 0 (nothing).
-
-       -separate_out2|so2 <string>
-              Separator after output prompts.  Default: 0 (nothing).
-
-       -nosep Shorthand for '-separate_in 0 -separate_out 0 -separate_out2 0'.
-              Simply removes all input/output separators.
-
-       -upgrade
-              Allows you to upgrade your  IPYTHON_DIR  configuration  when  you
-              install  a  new  version  of  IPython.   Since  new versions may
-              include new command lines options or example files, this  copies
-              updated ipythonrc-type files.  However, it backs up (with a .old
-              extension) all files which it overwrites so that you  can  merge
-              back any custimizations you might have in your personal files.
-
-       -Version
-              Print version information and exit.
-
-       -wxversion <string>
-              Select a specific version of wxPython (used in conjunction with
-              -wthread). Requires the wxversion module, part of recent
-              wxPython distributions.
-
-       -xmode <modename>
-              Mode  for  exception reporting.  The valid modes are Plain, Con-
-              text, 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 vari-
-              ables 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  repre-
-              sentation  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).
-
-
-EMBEDDING
-       It is possible to start an IPython instance inside your own Python pro-
-       grams.  In the documentation example files there are some illustrations
-       on how to do this.
-
-       This feature allows you to evalutate  dynamically  the  state  of  your
-       code,  operate  with  your  variables, analyze them, etc.  Note however
-       that any changes you make to values while in the shell do NOT propagate
-       back  to  the running code, so it is safe to modify your values because
-       you won't break your code in bizarre ways by doing so.
-"""
+IPython: an enhanced interactive Python shell.
+
+    A Python shell with automatic history (input and output), dynamic object
+    introspection, easier configuration, command completion, access to the
+    system shell and more.  IPython can also be embedded in running programs.
 
-cmd_line_usage = __doc__
+    If invoked with no options, it executes all the files listed in sequence
+    and exits, use -i to enter interactive mode after running the files.  Files
+    ending in .py will be treated as normal Python, but files ending in .ipy
+    can contain special IPython syntax (magic commands, shell expansions, etc.)
+
+    Please note that some of the configuration options are not available at the
+    command line, simply because they are not practical here. Look into your
+    ipython_config.py configuration file for details on those.
+
+    This file typically installed in the $HOME/.ipython directory.  For Windows
+    users, $HOME resolves to C:\\Documents and Settings\\YourUserName in most
+    instances.
+
+    In IPython's documentation, we will refer to this directory as IPYTHON_DIR,
+    you can change its default location by setting any path you want in this
+    environment variable.
+
+    For more information, see the manual available in HTML and PDF in your
+    installation, or online at http://ipython.scipy.org.
+"""
 
-#---------------------------------------------------------------------------
 interactive_usage = """
 IPython -- An enhanced Interactive Python
 =========================================