From 5234bee2cceb6ad20f9722383e1c7e23e3c2f107 2010-02-24 15:25:40
From: Fernando Perez <Fernando.Perez@berkeley.edu>
Date: 2010-02-24 15:25:40
Subject: [PATCH] Add notes by Brian on Mathematica notebook format.

---

diff --git a/docs/source/development/session_format.txt b/docs/source/development/session_format.txt
index ced6925..26b24d6 100644
--- a/docs/source/development/session_format.txt
+++ b/docs/source/development/session_format.txt
@@ -3,7 +3,11 @@
 ===============================
 
 This document serves as a sample/template for ideas on how to store session
-data on disk.  This stems from discussions we had on various mailing lists.
+data on disk.  This stems from discussions we had on various mailing lists, and
+should be considered a pure work in progress.  We haven't settled these ideas
+completely yet, and there's a lot to discuss; this document should just serve
+as a reference of the distilled points from various conversations on multiple
+mailing lists, and will congeal over time on a specific design we implement.
 
 The frontend would store, for now, 5 types of data:
 
@@ -50,3 +54,58 @@ The non-text cells would be stored on-disk as follows::
        :id: 3
 
        sh: askdfj: command not found
+
+Brian made some interesting points on the mailing list inspired by the
+Mathematica format, reproduced here for reference:
+
+The Mathematica notebook format is a plain text file that itself is *valid
+Mathematica code*.  This id documented here: 
+
+http://reference.wolfram.com/mathematica/guide/LowLevelNotebookProgramming.html
+
+For examples a simple notebook with one text cell is just::
+
+  Notebook[{Cell['Here is my text', 'Text']}]
+
+Everything - input cells, output cells, static images and all are represented
+in this way and embedded in the plain text notebook file.  The Python
+generalization of this would be the following: 
+
+* A Python notebook is plain text, importable Python code.
+
+* That code is simply a tree of objects that declare the relevant parts of the
+  notebook. 
+
+This has a number of advantages:
+
+* A notebook can be imported, manipulated and run by anyone who has the support
+  code (the notebook module that defines the relevant classes).
+  
+* A notebook doesn't need to be parsed.  It is valid Python and can be imported
+  or exec'd.  Once that is done, you have the full notebook in memory.  You can
+  immediately do anything you want with it.
+  
+* The various Notebook, Cell, Image, etc. classes can know about how to output
+  to various formats, latex, html, reST, XML, etc::
+
+  import mynotebook
+  mynotebook.notebook.export('rest')
+
+* Each individual format (HTML, reST, latex) has weaknesses.  If you pick any
+  one to be *the* notebook format, you are building those weaknesses into your
+  design.  A pure python based notebook format won't suffer from that syndrome.
+  
+* It is a clean separation of the model (Notebook, Cell, Image, etc.) and the
+  view (HTML, reST, etc.).  Picking HTML or reST for the notebook format
+  confuses (at some level) the model and view...
+  
+* Third party code can define new Notebook elements that specify how they can
+  be rendered in different contexts.  For example, matplotlib could ship a
+  Figure element that knows how to render itself as a native PyQt GUI, a static
+  image, a web page, etc.
+  
+* A notebook remains a single plain text file that anyone can edit - even if it
+  has embedded images.  Neither HTML nor reST have the ability to inline
+  graphics in plain text files.  While I love reST, it is a pain that I need an
+  entire directory of files to render a single Sphinx doc.
+  
\ No newline at end of file