Merge pull request ipython#27 from rgbkrk/on_ipython

Move the How IPython Works doc into a notebook

Author: rgbkrk

Index - Basic.ipynb

@@ -23,7 +23,7 @@
     "* [Introduction to Interactive Javascript Widgets](examples/Interactive Widgets/Using Interact.ipynb)\n",
     "* [Customizing IPython - a condensed version](exercises/Customization/Condensed.ipynb)\n",
     "* [Running a Secure Public Notebook Server](examples/Notebook/Running%20the%20Notebook%20Server.ipynb#Securing-the-notebook-server)\n",
-    "* [How Jupyter/IPython works](http://ipython.org/ipython-doc/stable/development/how_ipython_works.html) to run code in different languages."
+    "* [How Jupyter/IPython works](examples/Notebook/Multiple%20Languages%2C%20Frontends.ipynb) to run code in different languages."
    ]
   },
   {

examples/Notebook/Multiple Languages, Frontends.ipynb

@@ -0,0 +1,122 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# How IPython works\n",
+    "\n",
+    "\n",
+    "## Terminal IPython\n",
+    "\n",
+    "When you type `ipython`, you get the original IPython interface, running in\n",
+    "the terminal. It does something like this:\n",
+    "\n",
+    "```\n",
+    "while True:\n",
+    "    code = input(\">>> \")\n",
+    "    exec(code)\n",
+    "```\n",
+    "\n",
+    "Of course, it's much more complex, because it has to deal with multi-line\n",
+    "code, tab completion using `readline`, magic commands, and so on. But the\n",
+    "model is like that: prompt the user for some code, and when they've entered it,\n",
+    "exec it in the same process. This model is often called a REPL, or\n",
+    "Read-Eval-Print-Loop."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## The IPython Kernel\n",
+    "\n",
+    "All the other interfaces—the Notebook, the Qt console, `ipython console` in\n",
+    "the terminal, and third party interfaces—use the IPython Kernel. This is a\n",
+    "separate process which is responsible for running user code, and things like\n",
+    "computing possible completions. Frontends communicate with it using JSON\n",
+    "messages sent over [ZeroMQ](http://zeromq.org/) sockets; the protocol they use is described in\n",
+    ":doc:`messaging`.\n",
+    "\n",
+    "The core execution machinery for the kernel is shared with terminal IPython:\n",
+    "\n",
+    "![IPython kernel and terminal relationship](images/ipy_kernel_and_terminal.png)\n",
+    "\n",
+    "A kernel process can be connected to more than one frontend simultaneously. In\n",
+    "this case, the different frontends will have access to the same variables.\n",
+    "\n",
+    "<!-- TODO: Diagram illustrating this? -->\n",
+    "\n",
+    "This design was intended to allow easy development of different frontends based\n",
+    "on the same kernel, but it also made it possible to support new languages in the\n",
+    "same frontends, by developing kernels in those languages, and we are refining\n",
+    "IPython to make that more practical.\n",
+    "\n",
+    "Today, there are two ways to develop a kernel for another language. Wrapper\n",
+    "kernels reuse the communications machinery from IPython, and implement only the\n",
+    "core execution part. Native kernels implement execution and communications in\n",
+    "the target language:\n",
+    "\n",
+    "![Other Kernels](images/other_kernels.png)\n",
+    "\n",
+    "Wrapper kernels are easier to write quickly for languages that have good Python\n",
+    "wrappers, like [octave_kernel](https://pypi.python.org/pypi/octave_kernel), or\n",
+    "languages where it's impractical to implement the communications machinery, like\n",
+    "[bash_kernel](https://pypi.python.org/pypi/bash_kernel). Native kernels are\n",
+    "likely to be better maintained by the community using them, like\n",
+    "[IJulia](https://github.com/JuliaLang/IJulia.jl) or [IHaskell](https://github.com/gibiansky/IHaskell).\n",
+    "\n",
+    "<!-- TODO:\n",
+    ".. seealso::\n",
+    "\n",
+    "   :doc:`kernels`\n",
+    "   \n",
+    "   :doc:`wrapperkernels`\n",
+    "   \n",
+    "   -->"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Notebooks\n",
+    "\n",
+    "The Notebook frontend does something extra. In addition to running your code, it\n",
+    "stores code and output, together with markdown notes, in an editable document\n",
+    "called a notebook. When you save it, this is sent from your browser to the\n",
+    "notebook server, which saves it on disk as a JSON file with a ``.ipynb``\n",
+    "extension.\n",
+    "\n",
+    "![Notebook components](images/notebook_components.png)\n",
+    "\n",
+    "The notebook server, not the kernel, is responsible for saving and loading\n",
+    "notebooks, so you can edit notebooks even if you don't have the kernel for that\n",
+    "language—you just won't be able to run code. The kernel doesn't know anything\n",
+    "about the notebook document: it just gets sent cells of code to execute when the\n",
+    "user runs them."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.4.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}