notebook docs touchup

closes  #3902

incorporating doc changes from David Sanders, minor revisions my own

-@ivanov

docs/source/interactive/nbconvert.rst

@@ -67,7 +67,7 b' The currently supported export formats are:'
 * ``--to markdown``
 
   Simple markdown output.  Markdown cells are unaffected,
-  and code cells are placed in triple-backtick (``\`\`\```) blocks.
+  and code cells are placed in triple-backtick (```````) blocks.
 
 * ``--to rst``
 

docs/source/interactive/notebook.rst

@@ -102,14 +102,16 b' via the new nbconvert_ command.'
 
 Furthermore, any  ``.ipynb`` notebook document available from a public 
 URL can be shared via the `IPython Notebook Viewer <nbviewer>`_ service.
-This service loads the notebook document from the URL and will 
-render it as a static web page. The results may thus be shared with a 
+This service loads the notebook document from the URL and renders
+it as a static web page. The results may thus be shared with a 
 colleague, or as a public blog post, without other users needing to install 
-IPython themselves.  NbViewer is simply NbConvert as a simple heroku webservice.
+IPython themselves.  NbViewer is simply nbconvert_ as a simple webservice.
 
 See the :ref:`installation documentation <install_index>` for directions on
 how to install the notebook and its dependencies.
 
+.. _nbconvert: ./nbconvert.html
+
 .. _nbviewer: http://nbviewer.ipython.org
 
 .. note::
@@ -144,11 +146,11 b' source code files into the notebook list area.'
 
 
 You can open an existing notebook directly, without having to go via the 
-dashboard, with:
+dashboard, with::
 
   ipython notebook my_notebook
 
-The `.ipynb` extension is assumed if no extension is given.
+The ``.ipynb`` extension is assumed if no extension is given.
 
 The `File | Open...` menu option will open the dashboard in a new browser tab, 
 to allow you to select a current notebook 
@@ -313,19 +315,6 b' correctly. This is much more convenient for interactive exploration than'
 breaking up a computation into scripts that must be executed together, as was 
 previously necessary, especially if parts of them take a long time to run
 
-The only significant limitation that the Notebook currently has, compared to 
-the Qt console, is that it cannot run any code that expects input from the 
-kernel (such as scripts that call :func:`raw_input`).  Very importantly, this 
-means that the ``%debug`` magic does *not* currently work in the notebook!  
-
-This limitation will be overcome in the future, but in the meantime, there is 
-a simple solution for debugging: you can attach a Qt console to your existing 
-notebook kernel, and run ``%debug`` from the Qt console.
-If your notebook is running on a local computer (i.e. if you are accessing it 
-via your localhost address at ``127.0.0.1``), then you can just type 
-``%qtconsole`` in the notebook and a Qt console will open up, connected to 
-that same kernel.
-
 At certain moments, it may be necessary to interrupt a calculation which is 
 taking too long to complete. This may be done with the ``Kernel | Interrupt`` 
 menu option, or the :kbd:``Ctrl-i`` keyboard shortcut.
@@ -334,7 +323,12 b' process, with the ``Kernel | Restart`` menu option or :kbd:``Ctrl-.``'
 shortcut. This gives an equivalent state to loading the notebook document 
 afresh.
 
-    
+A notebook may be downloaded in either ``.ipynb`` or raw ``.py`` form from the
+menu option ``File | Download as``. Choosing the ``.py`` option downloads a
+Python ``.py`` script, in which all output has been removed and the content of
+Markdown cells  in comment areas.  See ref:`below <notebook_format>` for more
+details on the notebook format.
+
 .. warning::
 
    While in simple cases you can "roundtrip" a notebook to Python, edit the
@@ -558,14 +552,13 b' on available options, use::'
 
   $ ipython profile create
 
-.. seealso:
+.. seealso::
 
     :ref:`config_overview`, in particular :ref:`Profiles`.
 
 
-Importing `.py` files
-----------------------
-
+Importing ``.py`` files
+-----------------------
 
 ``.py`` files will be imported into the IPython Notebook as a notebook with 
 the same basename, but an ``.ipynb`` extension, located in the notebook 
@@ -574,8 +567,24 b' all the code in the ``.py`` file. You can later manually partition this into'
 individual cells using the ``Edit | Split Cell`` menu option, or the 
 :kbd:`Ctrl-m -` keyboard shortcut.
 
-.. Alternatively, prior to importing the ``.py``, you can manually add ``# <
-nbformat>2</nbformat>`` at the start of the file, and then add separators for 
-text and code cells, to get a cleaner import with the file already broken into 
-individual cells.
+Note that ``.py`` scripts obtained from a notebook document using nbconvert_ 
+maintain the structure of the notebook in comments. Reimporting such a
+script back into the Notebook will preserve this structxure.
 
+
+.. warning::
+
+   You can "roundtrip" a notebook to Python, by exporting the
+   notebook to a ``.py`` script, editing the script, and then importing it back
+   into the Notebook without loss of main content. However, 
+   in general this is *not guaranteed* to work.  First, there is extra metadata
+   saved in the notebook that may not be saved to the ``.py`` format.  Second,
+   as the notebook format evolves in complexity, there will be attributes of 
+   the notebook that will not survive a roundtrip through the Python form.  You
+   should think of the Python format as a way to output a script version of a
+   notebook and the import capabilities as a way to load existing code to get 
+   a notebook started.  But the Python version is *not* an alternate notebook
+   format.
+
+.. seealso::
+    :ref:`notebook_format`

docs/source/interactive/working_remotely.rst

@@ -5,10 +5,15 b' Working remotely'
 
 
 The IPython Notebook web app is based on a server-client structure. 
-This server uses a two-process kernel architecture based on ZeroMQ, as well as 
-Tornado for serving HTTP requests. Other clients may connect to the same 
+This server uses a two-process kernel architecture based on ZeroMQ_, as well
+as Tornado_ for serving HTTP requests. Other clients may connect to the same 
 underlying IPython kernel; see below.
 
+.. _ZeroMQ: http://zeromq.org
+
+.. _Tornado: http://www.tornadoweb.org
+
+
 .. _notebook_security:
 
 Security
@@ -58,7 +63,7 b' the command::'
 Your browser will warn you of a dangerous certificate because it is
 self-signed.  If you want to have a fully compliant certificate that will not
 raise warnings, it is possible (but rather involved) to obtain one,
-`as explained in detailed in this tutorial`__.
+as explained in detail in `this tutorial`__.
 
 .. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-
 secure-sertificate-for-free.ars