update docs to reflect relaxed syntax of argparse

docs/source/config/overview.txt

@@ -386,23 +386,39 b' Is the same as adding:'
 to your config file. Key/Value arguments *always* take a value, separated by '='
 and no spaces.
 
+Common Arguments
+****************
+
+Since the strictness and verbosity of the KVLoader above are not ideal for everyday
+use, common arguments can be specified as flags_ or aliases_.
+
+Flags and Aliases are handled by :mod:`argparse` instead, allowing for more flexible
+parsing. In general, flags and aliases are prefixed by ``--``, except for those
+that are single characters, in which case they can be specified with a single ``-``, e.g.:
+
+.. code-block:: bash
+
+    $> ipython -i -c "import numpy; x=numpy.linspace(0,1)" --profile testing --colors=lightbg
+
 Aliases
 -------
 
-For convenience, applications have a mapping of commonly
-used traits, so you don't have to specify the whole class name. For these **aliases**, the class need not be specified:
+For convenience, applications have a mapping of commonly used traits, so you don't have
+to specify the whole class name:
 
 .. code-block:: bash
 
+    $> ipython --profile myprofile
+    # and
     $> ipython --profile='myprofile'
-    # is equivalent to
+    # are equivalent to
     $> ipython --BaseIPythonApplication.profile='myprofile'
 
 Flags
 -----
 
 Applications can also be passed **flags**. Flags are options that take no
-arguments, and are always prefixed with ``--``. They are simply wrappers for
+arguments. They are simply wrappers for
 setting one or more configurables with predefined values, often True/False.
 
 For instance:
@@ -416,9 +432,13 b' For instance:'
     $> ipython --pylab
     # is equivalent to
     $> ipython --pylab=auto
+    # or
+    $> ipython --no-banner
+    # is equivalent to
+    $> ipython --TerminalIPythonApp.display_banner=False
 
 Subcommands
------------
+***********
 
 
 Some IPython applications have **subcommands**. Subcommands are modeled after

docs/source/interactive/reference.txt

@@ -83,7 +83,7 b' All options with a [no] prepended can be specified in negated form'
     ``--[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.
 
@@ -158,7 +158,7 b' All options with a [no] prepended can be specified in negated form'
         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``
+        logfile with ``ipython -i ipython_log.py``
 
     ``--logplay=<name>``
     

docs/source/parallel/parallel_intro.txt

@@ -205,7 +205,7 b' simply start a controller and engines on a single host using the'
 :command:`ipcluster` command. To start a controller and 4 engines on your
 localhost, just do::
 
-    $ ipcluster start --n=4
+    $ ipcluster start -n 4
 
 More details about starting the IPython controller and engines can be found
 :ref:`here <parallel_process>`

docs/source/parallel/parallel_mpi.txt

@@ -52,7 +52,7 b' The easiest approach is to use the `MPIExec` Launchers in :command:`ipcluster`,'
 which will first start a controller and then a set of engines using
 :command:`mpiexec`::
 
-    $ ipcluster start --n=4 --elauncher=MPIExecEngineSetLauncher
+    $ ipcluster start -n 4 --elauncher=MPIExecEngineSetLauncher
 
 This approach is best as interrupting :command:`ipcluster` will automatically
 stop and clean up the controller and engines.
@@ -105,7 +105,7 b' distributed array. Save the following text in a file called :file:`psum.py`:'
 
 Now, start an IPython cluster::
 
-    $ ipcluster start --profile=mpi --n=4
+    $ ipcluster start --profile=mpi -n 4
     
 .. note::
 

docs/source/parallel/parallel_multiengine.txt

@@ -19,7 +19,7 b' To follow along with this tutorial, you will need to start the IPython'
 controller and four IPython engines. The simplest way of doing this is to use
 the :command:`ipcluster` command::
 
-    $ ipcluster start --n=4
+    $ ipcluster start -n 4
     
 For more detailed information about starting the controller and engines, see
 our :ref:`introduction <parallel_overview>` to using IPython for parallel computing.

docs/source/parallel/parallel_process.txt

@@ -109,7 +109,7 b' The simplest way to use ipcluster requires no configuration, and will'
 launch a controller and a number of engines on the local machine. For instance, 
 to start one controller and 4 engines on localhost, just do::
 
-    $ ipcluster start --n=4
+    $ ipcluster start -n 4
 
 To see other command line options, do::
 
@@ -174,7 +174,7 b' There, instruct ipcluster to use the MPIExec launchers by adding the lines:'
 
 If the default MPI configuration is correct, then you can now start your cluster, with::
 
-    $ ipcluster start --n=4 --profile=mpi
+    $ ipcluster start -n 4 --profile=mpi
 
 This does the following:
 
@@ -324,7 +324,7 b' connections on all its interfaces, by adding in :file:`ipcontroller_config`:'
 
 You can now run the cluster with::
 
-    $ ipcluster start --profile=pbs --n=128
+    $ ipcluster start --profile=pbs -n 128
 
 Additional configuration options can be found in the PBS section of :file:`ipcluster_config`.
 

docs/source/parallel/parallel_task.txt

@@ -24,7 +24,7 b' To follow along with this tutorial, you will need to start the IPython'
 controller and four IPython engines. The simplest way of doing this is to use
 the :command:`ipcluster` command::
 
-	$ ipcluster start --n=4
+	$ ipcluster start -n 4
 	
 For more detailed information about starting the controller and engines, see
 our :ref:`introduction <parallel_overview>` to using IPython for parallel computing.

docs/source/parallel/parallel_winhpc.txt

@@ -257,7 +257,7 b' Starting the cluster profile'
 Once a cluster profile has been configured, starting an IPython cluster using
 the profile is simple::
 
-    ipcluster start --profile=mycluster --n=32
+    ipcluster start --profile=mycluster -n 32
 
 The ``-n`` option tells :command:`ipcluster` how many engines to start (in
 this case 32). Stopping the cluster is as simple as typing Control-C.