discuss `--to notebook`

- downgrade and execute examples
- also update `--to python` with `--to script`

docs/source/notebook/nbconvert.rst

@@ -78,18 +78,44 b' The currently supported export formats are:'
   Basic reStructuredText output. Useful as a starting point for embedding notebooks
   in Sphinx docs.
 
-* ``--to python``
+* ``--to script``
 
-  Convert a notebook to an executable Python script.
-  This is the simplest way to get a Python script out of a notebook.
-  If there were any magics in the notebook, this may only be executable from
+  Convert a notebook to an executable script.
+  This is the simplest way to get a Python (or other language, depending on the kernel) script out of a notebook.
+  If there were any magics in an IPython notebook, this may only be executable from
   an IPython session.
+
+* ``--to notebook``
+
+  .. versionadded:: 3.0
+  
+  This doesn't convert a notebook to a different format *per se*,
+  instead it allows the running of nbconvert preprocessors on a notebook,
+  and/or conversion to other notebook formats. For example::
+  
+      ipython nbconvert --to notebook --execute mynotebook.ipynb
+  
+  will open the notebook, execute it, capture new output, and save the result in
+  :file:`mynotebook.nbconvert.ipynb`.
+  
+  ::
+  
+      ipython nbconvert --to notebook --nbformat 3 mynotebook
+  
+  will create a copy of :file:`mynotebook.ipynb` in :file:`mynotebook.v3.ipynb`
+  in version 3 of the :ref:`notebook format <nbformat>`.
+  
+  If you want to convert a notebook in-place,
+  you can specify the ouptut file to be the same as the input file::
+  
+      ipython nbconvert --to notebook mynb --output mynb
+  
+  Be careful with that, since it will replace the input file.
   
 .. note::
 
   nbconvert uses pandoc_ to convert between various markup languages,
-  so pandoc is a dependency of most nbconvert transforms,
-  excluding Markdown and Python.
+  so pandoc is a dependency when converting to latex or reStructuredText.
 
 .. _pandoc: http://johnmacfarlane.net/pandoc/
 

docs/source/whatsnew/version3.rst

@@ -219,7 +219,7 b' Backwards incompatible changes'
 
   You can downgrade a notebook to v3 via ``nbconvert``::
   
-      ipython nbconvert --to notebook --nbformat 3 [notebook]
+      ipython nbconvert --to notebook --nbformat 3 <notebook>
   
   which will create :file:`notebook.v3.ipynb`, a copy of the notebook in v3 format.