[IPython-dev] first experiment creating Software Carpentry teaching materials using the IPython Notebook

[Greg Wilson]

Hi everyone,
Thanks for your replies --- mine are below.
- Greg

------------------------------------------------------------

 >> GVW:
 >> I want to put each logical thought in its own cell...I often want
 >> a small block of code in the middle of a thought.
 >> ...
 >> From what I understand, nested cells will do what I want here; any
 >> idea when they're likely to land in production?

 > MB:
 > Probably in the next 2 years. But not soon. We can try to work
 > around that with custom js extension and cell toolbar (cf below for
 > custom cell marking)

 > MRK:
 > We have no plans for nested cells per se.  Our current plan for
 > expressing document hierarchy is strictly with header cells, and
 > operating on the groupings implied by these headers - outline view,
 > tabbed view, reordering / hiding whole sections at a time, etc.  One
 > case this really doesn't serve is the code cell inside a paragraph
 > case.  We'll have to think about this one.

GVW:
OK --- if I can add a CSS class to a cell, I can do what I'm doing
right now with plain HTML (which is mark the second and subsequent
parts of a broken-to-pieces paragraph as 'continuation').

------------------------------------------------------------

 >> GVW:
 >> I want to have cells of type 'SVG', and be able to edit my diagrams
 >> in-browser using something like svg-edit.

 > MRK:
 > You can have SVG inlined in a markdown cell already, but an SVG-edit
 > widget would still be useful.

GVW:
One of the most compelling features of PowerPoint and its open source
clones is that they let people edit text and visuals side by side in a
single tool.  I don't know of any HTML-based slideshow tools that
support that; if the Notebook did, it would make it a lot of friends.

------------------------------------------------------------

 >> GVW:
 > Is there a way to say, "Re-set the In[*] counter to 1 and re-run all
 > cells in the current order"?

 > MB:
 > No, not possible, you could write js that does it, but the In[] and
 > Out[] represent kernel state.

 > MRK:
 > Prompt numbers are strictly and deliberately side effects of running
 > cells.  If you want to reset without restarting, you can call
 > `%reset` before doing 'run all'.  I do not think that we are going
 > to provide a mechanism for making any direct change to prompt
 > numbers (other than clearing them).

GVW:
Works for me.

------------------------------------------------------------

 >> GVW:
 >> What's the right way to link from one notebook to another?

GVW:
There's now another thread on this, so I'll drop it from this
discussion.

------------------------------------------------------------

 >> GVW:
 >> it would be _really_ nice if the notebook's Markdown was identical
 >> to GitHub's.

 > MB:
 > I agree that table would be nice too, and some of github feature
 > also like (triple-backquote-language) to select coloration.
 >
 > It is just too much to handle in the core for now. If/when we have
 > more manpower, that would be great.
 >
 > Still you could, with an extension, make the table from python code.

 > MRK:
 > We are extremely reticent to extend the markdown syntax, because
 > maintaining such a thing is well outside our core competency. We
 > have already found this to be troublesome with our one extension so
 > far - including mathjax.  *However*, tables are a part of
 > GitHub-flavored markdown, which all of us use every day.  So
 > perhaps we can get away with finding a javascript implementation of
 > GHM, in which case you would get tables as described here:
 > https://help.github.com/articles/github-flavored-markdown.

GVW:
Understood.  Am I right that if you could take Markdown rendering out
of the core entirely and use someone else's library, you would?

------------------------------------------------------------

 >> GVW:
 >> I want this [sample code] pretty-printed as Python, but do _not_
 >> want the notebook to try to execute it.

 > MB:
 > 4 space indent in MD cell should convert to "code" environment in
 > markdown.  Not sure if it colorize...

 > MIN:
 > If you indent a block four spaces in a markdown cell, it will be
 > highlighted as code, but is not a code cell, and thus will not be
 > executed.  This mechanism uses `prettify`, which infers the language
 > being used, and should highlight Python and shell blobs scripts
 > properly.

GVW:
Indenting four spaces in a Markdown cell mostly works --- the code is
colorized, but the background color is white instead of gray.  On the
other hand, since this code *isn't* actually being executed, that may
be a good thing.  It'll do for now...

------------------------------------------------------------

 >> GVW:
 >> And similarly, if I want to format cells to look like shell
 >> commands and their output (and then populate them with
 >> copy-and-paste), can I do that?

 > MB:
 > With extension, you could "lock" some cell. But the extension have
 > to be install on student notebooks.

GVW:
I'm OK with having students install a Software Carpentry extension ---
we're probably going to have to do that for other reasons anyway (e.g.,
to support in-class multiple choice quizzes).  Again, I think that if I
can label certain cells with classes, we can use that to trigger existing
bits of JS to colorize without executing.

------------------------------------------------------------

 >> GVW:
 >> Related to all of the above: I want some way to mark specific cells
 >> with classes.

 > MB:
 > That's on dev version. Arbitrary marking cell with tag in metadata
 > and a custom custom.css.
 > [details]
 > 
http://nbviewer.ipython.org/urls/raw.github.com/Carreau/posts/master/04-initialisation-cell.ipynb

 > MIN:
 > The API for this would be cell metadata - in master, activate the
 > cell toolbar to edit metadata for each cell.  We need to figure out
 > some mechanisms for what we do with cell metadata, and what we let
 > authors do with metdata in terms of UI and effects.  The very best
 > information on this is use cases people need, so we will definitely
 > keep this in mind as we work out the design.

GVW:
Cool!

------------------------------------------------------------

GVW:
Thank you both for your responses.  Given what you've said, the
priority on the things I want are:

1: Inter-notebook linking.

2: Marking cells with particular classes, which will then allow:

    2.1: Selectively showing/hiding different kinds of material in a
         single notebook.

    2.2: Styling (both during display, and when exporting to other
         formats like LaTeX).

3: An in-place SVG editing widget.

4: GitHub-compatible Markdown.

Sounds like #1 is under way; as per my original message, Fernando and
Brian tell me it doesn't make sense to think about #3 until mid- to
late summer.  #2 is in the dev version (at which point #2.1 and #2.2
become my responsibility) --- any idea when that lands in production?
And #4 is on me...

Thanks,
Greg