diff --git a/docs/source/interactive/htmlnotebook.rst b/docs/source/interactive/htmlnotebook.rst
index 7bd6354..c3d3467 100644
--- a/docs/source/interactive/htmlnotebook.rst
+++ b/docs/source/interactive/htmlnotebook.rst
@@ -74,8 +74,8 @@ how to install the notebook and its dependencies.
option.
-Running the IPython Notebook web app
-====================================
+Starting up the IPython Notebook web app
+----------------------------------------
The Notebook web app is started with the command::
@@ -148,24 +148,16 @@ At certain moments, it may be necessary to interrupt a particularly long calcula
After a restart, all relevant cells must be re-evaluated
-Saveing a notebook
-------------------
-
-The `Download` button lets you save a notebook file to the Download area
-configured by your web browser (particularly useful if you are running the
-notebook server on a remote host and need a file locally).
-But you can always export
-the input part of a notebook to a plain python script by choosing Python format
-in the `Download` drop list. This removes all output and saves the text cells
+A notebook may be downloaded in either ``.ipynb`` or raw ``.py`` form from the menu option ``File -> Download as``
+Choosing the ``.py`` option removes all output and saves the text cells
in comment areas. See ref:`below ` for more details on the
notebook format.
.. warning::
- While in simple cases you can roundtrip a notebook to Python, edit the
- python file and import it back without loss of main content, this is in
- general *not guaranteed to work at all*. First, there is extra metadata
+ While in simple cases you can "roundtrip" a notebook to Python, edit the
+ Python file, and then import it back without loss of main content, this is in general *not guaranteed to work*. First, there is extra metadata
saved in the notebook that may not be saved to the ``.py`` format. And 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
@@ -174,49 +166,35 @@ notebook format.
notebook started. But the Python version is *not* an alternate notebook
format.
-
-Importing or executing a notebook as a normal Python file
----------------------------------------------------------
-
-The native format of the notebook, a file with a ``.ipynb`` `extension, is a
-JSON container of all the input and output of the notebook, and therefore not
-valid Python by itself. This means that by default, you cannot directly
-import a notebook from Python, nor execute it as a normal python script.
-But if you want to be able to use notebooks also as regular Python files, you can start the notebook server with::
-
- ipython notebook --script
-
-or you can set this option permanently in your configuration file with::
-
- c.NotebookManager.save_script=True
-
-This will instruct the notebook server to save the ``.py`` export of each
-notebook, in addition to the ``.ipynb``, at every save. These are standard ``.py`` files, and so they can be
-``%run``, imported from regular IPython sessions or other notebooks, or
-executed at the command-line. Since we export the raw
-code you have typed, for these files to be importable from other code you will
-have to avoid using syntax such as ``%magics`` and other IPython-specific
-extensions to the language.
-
-In regular practice, the standard way to differentiate importable code from the
-'executable' part of a script is to put at the bottom::
+Keyboard shortcuts
+------------------
+All actions in the notebook can be achieved with the mouse, but we have also
+added keyboard shortcuts for the most common ones, so that productive use of
+the notebook can be achieved with minimal mouse intervention. The main
+key bindings you need to remember are:
- if __name__ == '__main__':
- # rest of the code...
+* :kbd:`Shift-Enter`:
+ execute the current cell, show output (if any), and jump
+ to the next cell below. If :kbd:`Shift-Enter`
+ was invoked on the last input line, a new code cell will also be created. Note that in the notebook, simply using :kbd:`Enter` *never* forces execution, it simply inserts a new line in the current cell. Therefore, in the notebook you must always use :kbd:`Shift-Enter` to get execution (or use the mouse and click on the ``Run Selected`` button).
-Since all cells in the notebook are run as top-level code, you'll need to
-similarly protect *all* cells that you do not want executed when other scripts
-try to import your notebook. A convenient shortand for this is to define early
-on::
+* :kbd:`Alt-Enter`:
+ this combination is similar to the previous one, with the
+ exception that, if the next cell below is not empty, a new code cell will be
+ added to the notebook, even if the cell execution happens not in the last cell. :kbd:`Alt-Enter`: is a shortcut for the sequence :kbd:`Shift-Enter`, :kbd:`Ctrl-m a`.
+
+* :kbd:`Ctrl-Enter`:
+ execute the current cell in "terminal mode", where any
+ output is shown, but the cursor remains in the current cell. This is convenient to do quick in-place experiments, or query things like filesystem content, without creating additional cells that you may not want saved in your notebook.
- script = __name__ == '__main__'
+* :kbd:`Ctrl-m`:
+ this is the prefix for all other keybindings, which consist of an additional single letter or character. Type :kbd:`Ctrl-m h` (that is, the sole letter
+ :kbd:`h` after :kbd:`Ctrl-m`) and IPython will show you the remaining available keybindings.
-and then on any cell that you need to protect, use::
- if script:
- # rest of the cell...
+
Cell types
----------
@@ -305,20 +283,44 @@ When the default ``%matplotlib`` or ``%pylab`` magics are used, the output of a
``%matplotlib inline``
which captures the output inline within the notebook format. This has the benefit that the resulting plots will be stored in the notebook document.
-Converting notebooks to other formats using nbconvert
-------------------------------------------------------
+
+Converting notebooks to other formats
+-------------------------------------
+Newly added in the 1.0 release of IPython is the ``nbconvert`` tool to convert a notebook document into another static format. This is a command line tool; at present, this functionality is not available to export directly from within the Notebook app. The syntax is::
+
+ ``$ ipython nbconvert notebook.ipynb``
+
+for standard HTML output, or::
+
+ ``$ ipython nbconvert --format=FORMAT notebook.ipynb``
+
+where ``FORMAT`` is the desired export format. Options for this format include:
+
+* ``full_html``:
+ Standard HTML
+
+* ``simple_html``:
+ A simplified version of HTML
+
+* ``reveal``:
+ A format to be used with the ``reveal.js`` package for slideshow presentations.
+
+* ``sphinx_howto``:
+ A standard documentation format.
+
+* ``latex``:
+ Produces LaTeX output which may be compiled with ``pdflatex`` to PDF.
Configuration
-------------
-
-The IPython notebook server can be run with a variety of command line arguments.
+The IPython Notebook can be run with a variety of command line arguments.
To see a list of available options enter::
$ ipython notebook --help
Defaults for these options can also be set by creating a file named
-``ipython_notebook_config.py`` in your IPython profile folder. The profile folder is a subfolder of your IPython directory; ``ipython locate`` will show you where it is located.
+``ipython_notebook_config.py`` in your IPython *profile folder*. The profile folder is a subfolder of your IPython directory; ``ipython locate`` will show you where it is located.
To create a new set of default configuration files, with lots of information on available options, use::
@@ -329,38 +331,47 @@ To create a new set of default configuration files, with lots of information on
:ref:`config_overview`, in particular :ref:`Profiles`.
-Keyboard shortcuts
-------------------
-All actions in the notebook can be achieved with the mouse, but we have also
-added keyboard shortcuts for the most common ones, so that productive use of
-the notebook can be achieved with minimal mouse intervention. The main
-key bindings you need to remember are:
+Importing or executing a notebook as a normal Python file
+---------------------------------------------------------
-* :kbd:`Shift-Enter`: execute the current cell (similar to the Qt console),
- show output (if any) and jump to the next cell below. If :kbd:`Shift-Enter`
- was invoked on the last input line, a new code cell will also be created. Note
- that in the notebook, simply using :kbd:`Enter` *never* forces execution,
- it simply inserts a new line in the current cell. Therefore, in the notebook
- you must always use :kbd:`Shift-Enter` to get execution (or use the mouse and
- click on the ``Run Selected`` button).
+The native format of the notebook, a file with a ``.ipynb`` `extension, is a
+JSON container of all the input and output of the notebook, and therefore not
+valid Python by itself. This means that by default, you cannot directly
+import a notebook from Python, nor execute it as a normal python script.
-* :kbd:`Alt-Enter`: this combination is similar to the previous one, with the
- exception that, if the next cell below is not empty, a new code cell will be
- added to the notebook, even if the cell execution happens not in the last cell.
- In this regard, :kbd:`Alt-Enter`: is simply a shortcut for the :kbd:`Shift-Enter`,
- :kbd:`Ctrl-m a` sequence.
-
-* :kbd:`Ctrl-Enter`: execute the current cell in "terminal mode", where any
- output is shown but the cursor stays in the current cell, whose input
- area is flushed empty. This is convenient to do quick in-place experiments
- or query things like filesystem content without creating additional cells you
- may not want saved in your notebook.
-
-* :kbd:`Ctrl-m`: this is the prefix for all other keybindings, which consist
- of an additional single letter. Type :kbd:`Ctrl-m h` (that is, the sole
- letter :kbd:`h` after :kbd:`Ctrl-m`) and IPython will show you the remaining
- available keybindings.
+But if you want to be able to use notebooks also as regular Python files, you can start the notebook server with::
+
+ ipython notebook --script
+
+or you can set this option permanently in your configuration file with::
+
+ c.NotebookManager.save_script=True
+
+This will instruct the notebook server to save the ``.py`` export of each
+notebook, in addition to the ``.ipynb``, at every save. These are standard
+``.py`` files, and so they can be ``%run``, imported from regular IPython
+sessions or other notebooks, or executed at the command line. Since we export
+the raw code you have typed, for these files to be importable from other code,
+you will have to avoid using syntax such as ``%magic``s and other IPython-specific extensions to the language.
+
+In regular practice, the standard way to differentiate importable code from the
+'executable' part of a script is to put at the bottom::
+
+ if __name__ == '__main__':
+ # rest of the code...
+
+Since all cells in the notebook are run as top-level code, you will need to
+similarly protect *all* cells that you do not want executed when other scripts
+try to import your notebook. A convenient shortand for this is to define early
+on::
+
+ script = __name__ == '__main__'
+
+and then on any cell that you need to protect, use::
+
+ if script:
+ # rest of the cell...
.. _notebook_security: