Fix regressions notice as per Thomas' comments.

docs/source/interactive/qtconsole.txt

@@ -1,331 +1,341 b''
 .. _qtconsole:
 
 =========================
 A Qt Console for IPython
 =========================
 
 We now have a version of IPython, using the new two-process :ref:`ZeroMQ Kernel
 <ipythonzmq>`, running in a PyQt_ GUI.  This is a very lightweight widget that
 largely feels like a terminal, but provides a number of enhancements only
 possible in a GUI, such as inline figures, proper multiline editing with syntax
 highlighting, graphical calltips, and much more.
 
 .. figure:: ../_static/qtconsole.png
     :width: 400px
     :alt: IPython Qt console with embedded plots
     :align: center
     :target: ../_static/qtconsole.png
 
     The Qt console for IPython, using inline matplotlib plots.
 
 To get acquainted with the Qt console, type `%guiref` to see a quick
 introduction of its main features.
 
 The Qt frontend has hand-coded emacs-style bindings for text navigation. This
 is not yet configurable.
 
 .. tip::
 
    Since the Qt console tries hard to behave like a terminal, by default it
    immediately executes single lines of input that are complete.  If you want
    to force multiline input, hit :key:`Ctrl-Enter` at the end of the first line
    instead of :key:`Enter`, and it will open a new line for input.  At any
    point in a multiline block, you can force its execution (without having to
    go to the bottom) with :key:`Shift-Enter`.
 
 ``%loadpy``
 ===========
 
 The new ``%loadpy`` magic takes any python script (must end in '.py'), and
 pastes its contents as your next input, so you can edit it before
 executing. The script may be on your machine, but you can also specify a url,
 and it will download the script from the web. This is particularly useful for
 playing with examples from documentation, such as matplotlib.
 
 .. sourcecode:: ipython
 
     In [6]: %loadpy http://matplotlib.sourceforge.net/plot_directive/mpl_examples/mplot3d/contour3d_demo.py
 
     In [7]: from mpl_toolkits.mplot3d import axes3d
        ...: import matplotlib.pyplot as plt
        ...: 
        ...: fig = plt.figure()
        ...: ax = fig.add_subplot(111, projection='3d')
        ...: X, Y, Z = axes3d.get_test_data(0.05)
        ...: cset = ax.contour(X, Y, Z)
        ...: ax.clabel(cset, fontsize=9, inline=1)
        ...: 
        ...: plt.show()
 
 Pylab
 =====
 
 One of the most exciting features of the new console is embedded matplotlib
 figures. You can use any standard matplotlib GUI backend (Except native MacOSX)
 to draw the figures, and since there is now a two-process model, there is no
 longer a conflict between user input and the drawing eventloop.
 
 .. image:: figs/besselj.png
     :width: 519px
 
 .. display:
 
 :func:`display`
 ***************
 
 An additional function, :func:`display`, will be added to the global namespace
 if you specify the ``--pylab`` option at the command line. The IPython display
 system provides a mechanism for specifying PNG or SVG (and more)
 representations of objects for GUI frontends. By default, IPython registers
 convenient PNG and SVG renderers for matplotlib figures, so you can embed them
 in your document by calling :func:`display` on one or more of them. This is
 especially useful for saving_ your work.
 
 .. sourcecode:: ipython
 
     In [5]: plot(range(5)) # plots in the matplotlib window
     
     In [6]: display(gcf()) # embeds the current figure in the qtconsole
     
     In [7]: display(*getfigs()) # embeds all active figures in the qtconsole
 
 If you have a reference to a matplotlib figure object, you can always display
 that specific figure:
 
 .. sourcecode:: ipython
 
    In [1]: f = figure()
 
    In [2]: plot(rand(100))
    Out[2]: [<matplotlib.lines.Line2D at 0x7fc6ac03dd90>]
 
    In [3]: display(f)
 
    # Plot is shown here
 
    In [4]: title('A title')
    Out[4]: <matplotlib.text.Text at 0x7fc6ac023450>
 
    In [5]: display(f)
 
    # Updated plot with title is shown here.
 
 .. _inline:
 
 ``--pylab=inline``
 ******************
 
 If you want to have all of your figures embedded in your session, instead of
 calling :func:`display`, you can specify ``--pylab=inline`` when you start the
 console, and each time you make a plot, it will show up in your document, as if
 you had called :func:`display(fig)`.
 
 
 .. _saving:
 
 Saving and Printing
 ===================
 
 IPythonQt has the ability to save your current session, as either HTML or
 XHTML. If you have been using :func:`display` or inline_ pylab, your figures
 will be PNG in HTML, or inlined as SVG in XHTML. PNG images have the option to
 be either in an external folder, as in many browsers' "Webpage, Complete"
 option, or inlined as well, for a larger, but more portable file.
 
 The widget also exposes the ability to print directly, via the default print
 shortcut or context menu.
 
 
 .. Note:: 
 
     Saving is only available to richtext Qt widgets, which are used by default,
     but if you pass the ``--plain`` flag, saving will not be available to you.
 
 
 See these examples of :download:`png/html<figs/jn.html>` and
 :download:`svg/xhtml <figs/jn.xhtml>` output. Note that syntax highlighting
 does not survive export. This is a known issue, and is being investigated.
 
 Colors and Highlighting
 =======================
 
 Terminal IPython has always had some coloring, but never syntax
 highlighting. There are a few simple color choices, specified by the ``colors``
 flag or ``%colors`` magic:
 
 * LightBG for light backgrounds
 * Linux for dark backgrounds
 * NoColor for a simple colorless terminal
 
 The Qt widget has full support for the ``colors`` flag used in the terminal shell.
 
 The Qt widget, however, has full syntax highlighting as you type, handled by
 the `pygments`_ library. The ``style`` argument exposes access to any style by
 name that can be found by pygments, and there are several already
 installed. The ``colors`` argument, if unspecified, will be guessed based on
 the chosen style. Similarly, there are default styles associated with each
 ``colors`` option.
 
 
 Screenshot of ``ipython qtconsole --colors=linux``, which uses the 'monokai'
 theme by default:
 
 .. image:: figs/colors_dark.png
     :width: 627px
     
 .. Note::
 
     Calling ``ipython qtconsole -h`` will show all the style names that
     pygments can find on your system.
 
 You can also pass the filename of a custom CSS stylesheet, if you want to do
 your own coloring, via the ``stylesheet`` argument.  The default LightBG
 stylesheet:
 
 .. sourcecode:: css
 
     QPlainTextEdit, QTextEdit { background-color: white;
             color: black ;
             selection-background-color: #ccc}
     .error { color: red; }
     .in-prompt { color: navy; }
     .in-prompt-number { font-weight: bold; }
     .out-prompt { color: darkred; }
     .out-prompt-number { font-weight: bold; }
 
 Fonts
 =====
 
 The QtConsole has configurable via the ConsoleWidget. To change these, set the
 ``font_family`` or ``font_size`` traits of the ConsoleWidget. For instance, to
 use 9pt Anonymous Pro::
 
     $> ipython qtconsole --ConsoleWidget.font_family="Anonymous Pro" --ConsoleWidget.font_size=9
 
 Process Management
 ==================
 
 With the two-process ZMQ model, the frontend does not block input during
 execution. This means that actions can be taken by the frontend while the
 Kernel is executing, or even after it crashes. The most basic such command is
 via 'Ctrl-.', which restarts the kernel.  This can be done in the middle of a
 blocking execution. The frontend can also know, via a heartbeat mechanism, that
 the kernel has died. This means that the frontend can safely restart the
 kernel.
 
 Multiple Consoles
 *****************
 
 Since the Kernel listens on the network, multiple frontends can connect to it.
 These do not have to all be qt frontends - any IPython frontend can connect and
 run code.  When you start ipython qtconsole, there will be an output line,
 like::
 
     [IPKernelApp] To connect another client to this kernel, use:
     [IPKernelApp] --existing --shell=60690 --iopub=44045 --stdin=38323 --hb=41797
 
 Other frontends can connect to your kernel, and share in the execution. This is
 great for collaboration. The `-e` flag is for 'external'. Starting other
 consoles with that flag will not try to start their own, but rather connect to
 yours. Ultimately, you will not have to specify each port individually, but for
 now this copy-paste method is best.
 
 By default (for security reasons), the kernel only listens on localhost, so you
 can only connect multiple frontends to the kernel from your local machine. You
 can specify to listen on an external interface by specifying the ``ip``
 argument::
 
     $> ipython qtconsole --ip=192.168.1.123
 
 If you specify the ip as 0.0.0.0, that refers to all interfaces, so any
 computer that can see yours can connect to the kernel.
 
 .. warning::
 
     Since the ZMQ code currently has no security, listening on an
     external-facing IP is dangerous.  You are giving any computer that can see
     you on the network the ability to issue arbitrary shell commands as you on
     your machine. Be very careful with this.
 
 
 Stopping Kernels and Consoles
 *****************************
 
 Since there can be many consoles per kernel, the shutdown mechanism and dialog
 are probably more complicated than you are used to. Since you don't always want
 to shutdown a kernel when you close a window, you are given the option to just
 close the console window or also close the Kernel and *all other windows*. Note
 that this only refers to all other *local* windows, as remote Consoles are not
 allowed to shutdown the kernel, and shutdowns do not close Remote consoles (to
 allow for saving, etc.).
 
 Rules:
 
     * Restarting the kernel automatically clears all *local* Consoles, and prompts remote
       Consoles about the reset.
     * Shutdown closes all *local* Consoles, and notifies remotes that
       the Kernel has been shutdown.
     * Remote Consoles may not restart or shutdown the kernel.
 
 Qt and the QtConsole
 ====================
 
 An important part of working with the QtConsole when you are writing your own
 Qt code is to remember that user code (in the kernel) is *not* in the same
 process as the frontend.  This means that there is not necessarily any Qt code
 running in the kernel, and under most normal circumstances there isn't. If,
 however, you specify ``--pylab=qt`` at the command-line, then there *will* be a
 :class:`QCoreApplication` instance running in the kernel process along with
 user-code. To get a reference to this application, do:
 
 .. sourcecode:: python
 
     from PyQt4 import QtCore
     app = QtCore.QCoreApplication.instance()
     # app will be None if there is no such instance
 
 A common problem listed in the PyQt4 Gotchas_ is the fact that Python's garbage
 collection will destroy Qt objects (Windows, etc.) once there is no longer a
 Python reference to them, so you have to hold on to them.  For instance, in:
 
 .. sourcecode:: python
 
     def make_window():
         win = QtGui.QMainWindow()
     
     def make_and_return_window():
         win = QtGui.QMainWindow()
         return win
 
 :func:`make_window` will never draw a window, because garbage collection will
 destroy it before it is drawn, whereas :func:`make_and_return_window` lets the
 caller decide when the window object should be destroyed.  If, as a developer,
 you know that you always want your objects to last as long as the process, you
 can attach them to the QApplication instance itself:
 
 .. sourcecode:: python
     
     # do this just once:
     app = QtCore.QCoreApplication.instance()
     app.references = set()
     # then when you create Windows, add them to the set
     def make_window():
         win = QtGui.QMainWindow()
         app.references.add(win)
 
 Now the QApplication itself holds a reference to ``win``, so it will never be
 garbage collected until the application itself is destroyed.
 
 .. _Gotchas: http://www.riverbankcomputing.co.uk/static/Docs/PyQt4/html/gotchas.html#garbage-collection
 
 Regressions
 ===========
 
 There are some features, where the qt console lags behind the Terminal
-frontend. We hope to have these fixed by 0.11 release.
+frontend:
 
 * !cmd input: Due to our use of pexpect, we cannot pass input to subprocesses
-   launched using the '!' escape. (this will not be fixed).
+   launched using the '!' escape, so you should never call a command that
+   requires interactive input.  For such cases, use the terminal IPython.  This
+   will not be fixed, as abandoning pexpect would significantly degrade the
+   console experience.
+
+* Use of ``\b`` and ``\r`` characters in the console: these are control
+  characters that allow the cursor to move backwards on a line, and are used to
+  display things like in-place progress bars in a terminal.  We currently do
+  not support this, but it is being tracked as issue 629_.
+
+.. _629:  https://github.com/ipython/ipython/issues/629
 
 .. [PyQt] PyQt4 http://www.riverbankcomputing.co.uk/software/pyqt/download
 .. [pygments] Pygments http://pygments.org/