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