[IPython-dev] notebook questions

[Brian Granger]

I can outline our plans for supporting reST in the notebook.

* The problem with reST is that it can only render entire documents
and not parts of documents.  Because of this, it can't be used to
render a single reST text cell in any way that behaves as people
expect.  Examples are section headings and references, which are
contextual and require the entire document to make sense of.  A more
formal way of putting this is:

rest_render(cell[0]) + rest_render(cell[1]) != rest_render(cell[0] + cell[1])

Markdown does not suffer from these design limitations and this is why
it is our default for rich text cells in the notebook.

* Obviously reST is very important to the python community and we want
to support reST.  Here is how we plan on doing this.  The problem is
in the rendering of individual cells.  We will implement reST text
cells that simply don't render to HTML in the notebook as the Markdown
cells do.  They will remain reST source and be stored in that form in
the notebook format.

* Notebooks with reST text cells can be exported to reST easily and
then rendered to HTML/LaTeX as desired.

* reST document will be able to be imported into the notebook once
this is implemented as well.

The most important point in all of this is that the problem is reST
itself, not the IPython notebook.  I actually spent a couple of days
trying to hack reST support into the notebook using various tricks.
At the end of it all my conclusion was a somewhat depressing "wow,
reST is simply not designed for this usage case, but Markdown is a
perfect fit"

Cheers,

Brian

On Fri, Sep 16, 2011 at 9:17 PM, MinRK <benjaminrk at gmail.com> wrote:
>
>
> On Fri, Sep 16, 2011 at 20:44, Gael Varoquaux
> <gael.varoquaux at normalesup.org> wrote:
>>
>> On Fri, Sep 16, 2011 at 08:41:23PM -0700, MinRK wrote:
>> >      I noticed that github allows you to choose between several
>> > different
>> >      languages for wiki input so I thought you might have something like
>> >      that in mind.  I've been using reST for docstrings, sphinx docs,
>> > and
>> >      github so I selfishly would prefer not to have to learn another
>> >      simplified markup language.
>>
>> >    That makes sense, and I expect we will get this request often.  The
>> >    problem is reST is really a horrible language
>> >    for in-browser cell markup (as opposed to full document markup, for
>> > which
>> >    it is designed),
>>
>> Actually, reST was originally designed to write docstrings.
>
> Ah, I didn't know that, given that its design is so much better suited to
> large documents than small isolated text.
>
>>
>> It seems to me wrong to go with any other markup language, given that the
>> standard in the Python world in reST. It is hard enough to agree on
>> standards, let us rejoice that there is one.
>
> We thought about this quite a bit, and concluded that markdown was just a
> better
> fit, despite the Python-ness of reST.  reST is just a very bad tool for
> interactive, light text markup,
> but if you can point me to a good javascript reST renderer, we can
> reconsider.
>
>>
>> Gael
>
>
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev
>
>



-- 
Brian E. Granger
Cal Poly State University, San Luis Obispo
bgranger at calpoly.edu and ellisonbg at gmail.com