Deleted section on printing, which is no longer valid. Renamed 'exporting' to 'saving' and moved to Basic workflow. Renamed 'basic concepts' to 'user interface'.

docs/source/interactive/htmlnotebook.rst

@@ -100,8 +100,8 b' When you open or create a new notebook, your browser tab will reflect the name o'
 The URL is currently not meant to be human-readable and is not persistent across invocations of the notebook server; however, this will change in a future version of IPython.
 
 
-Basic concepts in the Notebook app
-----------------------------------
+Notebook user interface
+-----------------------
 
 When you finally start editing a notebook document in the Notebook, you will be presented with the title of the notebook, a *menu bar*, a *toolbar* and an empty *input cell*.
 
@@ -148,6 +148,76 b' 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
+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
+   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
+   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
+   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.
+
+   
+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::
+
+  if __name__ == '__main__':
+    # rest of the code...
+
+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::
+
+  script = __name__ == '__main__'
+
+and then on any cell that you need to protect, use::
+
+  if script:
+    # rest of the cell...
+
+
 Cell types
 ----------
 Each IPython input cell has a *cell type*.
@@ -178,7 +248,6 b' Raw cells'
 Raw cells provide a place to put additional information which is not evaluated by the Notebook. This can be used, for example, for extra information to be used when the notebook is exported to a certain format.
 
 
-
 Magic commands
 --------------
 Magic commands, or *magics*, are one-word commands beginning with the symbol ``%``, which send commands to IPython itself (as opposed to standard Python commands which are exported to be run in a Python interpreter).
@@ -189,7 +258,6 b' There are two types of magics: *line magics*, which begin with a single ``%`` an'
 
 Line magics
 ˜˜˜˜˜˜˜˜˜˜˜
-
 Some of the available line magics are the following:
 
 * ``%load``:
@@ -207,7 +275,17 b' Some of the available line magics are the following:'
 Cell magics
 ˜˜˜˜˜˜˜˜˜˜˜
 
-* ``%load``:
+* ``%%bash``:
+  Send the contents of the code cell to be executed by ``bash``
+
+* ``%%file``:
+  Writes a file with with contents of the cell. *Caution*: The file is ovewritten without asking.
+
+* ``%%R``:
+  Execute the contents of the cell using the R language.
+
+* ``%%cython``:
+  Execute the contents of the cell using ``Cython``.
   
 
 
@@ -227,87 +305,10 b' 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
+------------------------------------------------------
 
 
-Exporting a notebook and importing existing scripts
----------------------------------------------------
-
-Need to talk about ipython nbconvert
-
-If you want to provide others with a static HTML or PDF view of your notebook,
-use the ``Print`` button.  This opens a static view of the document, which you
-can print to PDF using your operating system's facilities, or save to a file
-with your web browser's 'Save' option (note that typically, this will create
-both an html file *and* a directory called `notebook_name_files` next to it
-that contains all the necessary style information, so if you intend to share
-this, you must send the directory along with the main html file).
-
-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
-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
-   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
-   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
-   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.
-
-   
-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::
-
-  if __name__ == '__main__':
-    # rest of the code...
-
-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::
-
-  script = __name__ == '__main__'
-
-and then on any cell that you need to protect, use::
-
-  if script:
-    # rest of the cell...
-
 Configuration
 -------------