add note about working with qt in two-process qtconsole

closes gh-505

docs/source/interactive/qtconsole.txt

@@ -208,6 +208,55 b' Rules:'
       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
 ===========