[IPython-dev] prose, notebooks, and thrashing (and a re-direct to another list)

[Matthias BUSSONNIER]

Hi Greg, 

Le 29 juil. 2013 à 17:13, Greg Wilson a écrit :

> Hi,
> I posted the message below to the Software Carpentry discussion list a 
> few minutes ago.  I'd appreciate input from the IPython Notebook 
> community as well.
> Thanks,
> Greg
> p.s. if anyone has a good way to manage discussion that spans two 
> independent mailing lists, I'm all ears... :-)

I'll be carefull to click reply all :-)

Most of the point you are making were discussed during last week meeting.
TL DR, depending on the case , it already exist, or you will have to wait for 2.0.

Answer inline

> My four use cases are:
> 
> * instructor's guide: to help instructors prepare for a bootcamp
> * lecture notes: what instructors use during a bootcamp
> * workbook: what learners are given to use during a bootcamp
> * textbook: what learners use on their own outside a bootcamp
> 


> Problem #1: how do we manage material that ought to appear in multiple 
> documents?  Right now, each snippet is a separate HTML file that is 
> %include'd to assemble the entire document (see 
> https://raw.github.com/swcarpentry/bc/gh-pages/lessons/guide-shell/tutorial.html). 
> That works OK for HTML pages, but not for notebooks: as far as I know, 
> there's no way to %include file X in notebook Y.

2.0 and probably will need dexy. (http://www.dexy.it/)
right now you can import one notebook as a python package 
We will add the possibility to add cell tags (~css .class selector) and cell name (~ html #id)
to refer to cell in conversion proccess.

[NDR, you can already attach arbitrary json to cells, it's just a matter of defining an expected structure.
Thoses data are already accessible in nbconvert if you want some cells not to appear in converted output.
]

> * If the item I'm currently talking about is centered on the screen, 
> learners can see my next points on screen below it.  This is distracting 
> --- so distracting that tools like PowerPoint and other slideshow tools 
> were invented in part to prevent it happening.  If the notebook 
> supported progressive reveal of pre-made cells, that problem would lessen.

... Have you seen slideshow mode ?
Have a look at F. Perez, B Granger and P. Ivanov talk ant las scipy.

Show cell one by one, skip some cells... etc
this is still a live notebook so you can execute cells live.
(won't provide the link as it is still in dev but google is your friend)


> 
> * Even with that, though, one of the most compelling reasons to use the 
> notebook as a lecture tool is lost.  Learners really like us typing code 
> in as we teach: it slows us down, which makes it more likely that we'll 
> walk through the code at a comprehensible pace, and it makes it a lot 
> easier for us to extemporize in response to their questions or 
> confusion.  We lose both benefits if we start using "reveal next", 
> though we're still better off than if we use slides.

I had a POC of revealing code cell by blocks.

> ...
> 
> * (medium-sized) In order to extract stuff from notebooks for use 
> elsewhere, we need a way to tag the cells that contain objectives, notes 
> for the key point summary, etc., so that our tool can find and 
> differentiate them.  I *think* this can be done via a plugin: the 
> notebook has an extensible metadata field per cell, which we've already 
> exploited for another tool, so adding something that allows "right click 
> and select tag" should be straightforward. It would be nice if this info 
> was available as a class on the HTML element containing the material, so 
> that it could be styled via CSS, but that's a bonus.

Yes, that's on my todo list. This would require SC to ship notebook with custom profiles.
There is just some edge cases at loading time.

> 
> * (large) Literal ________'s in our code will make it invalid, so our 
> notebooks either won't have any output (because we didn't execute the 
> code) or will be littered with error messages (because we did).  The 
> former's not bad, but if we do that, we need two version of each 
> notebook: one with the blanks, and one with them filled in.  As always, 
> keeping variants of a single document in sync will be a pain.

You could store the "answers" into the metadata of each cell that maps the Nth ____
to it's value. We can come up with something.

> 
> If the code in cells was stored as HTML, we could put something like 
> <span class="fillin">char == "A"</span> in the code, then use Javascript 
> to display ________, erase it when the learner started typing, or fill 
> it in with the right answer when the learner just wanted to catch up or 
> see the answer. Problem is, the code *isn't* stored as HTML; it's stored 
> as JSON that looks like this:

If you are diving into implementation I would have something like notebook creator typing:

 for §char§ in "GATTACA":
        if §char == "A"§:
            print "found an A"

and a cell toolbar button that store this in the json MD, and at load time you can live replace by ____
or strip the §. it should even be possible to add a execute hook to code cell that strip the § before running the cell
which would be convenient.

Not sure on how to live replace ___ if learner start typing though.


> We could use character offsets to identify subsections of the code, then 
> intercept rendering to insert span elements, but that way lies madness...
> 
> So as I said at the outset, I feel like I'm thrashing here, and would 
> welcome suggestions on how to proceed.

Will gladly try to help, most of what you ask is often requested, and I would love to have more time to help.
Sadly PhD (and code IPython first), but I'll try to describe in a blog post how most of thoses things can be done.
It will just take me some time as I wish to do them well instead of just publishing a hawkish POC.

-- 
Matthias