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

Greg Wilson gvwilson@third-bit....
Sun Mar 24 07:16:25 CDT 2013

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

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:

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