Manage handouts

[drjwbaker]

Referring to https://github.com/data-lessons/library-openrefine/issues/60#issuecomment-301086272 ensure that:

1) There is a place for handouts in each lesson repo 2) There is a place for handouts on each lesson website 3) There is a suggested workflow for converting .md to presentations formats so that instructors can print handouts with ease. Recommend both programmatic workflow (eg Pandoc) and GUI/web-based (eg http://dillinger.io/)

[weaverbel]

@drjwbaker Do you want to add to this issue that we would like the handouts created as well? I think we should let people make handouts based on the lessons.I will put 'create handouts' as another sprint job in the README.

[drjwbaker]

@weaverbel I'd leave it as down to the lesson maintainers. I'm seeing @jt14den this week, so I'll speak to him about maintaining shell handout (I tend to use one and have a starting point that can be used for this).

[drjwbaker]

How is this for instructor notes on making a handout? http://data-lessons.github.io/library-data-intro/guide/ Comments from other lesson maintainers appreciated @ccronje @weaverbel @ostephens @mkuzak @jezcope

[mkuzak]

@drjwbaker looks good pandoc is quite a heavy dependency, it's nice to have an alternative with dillinger.io I was wondering if there is an open source, multiplatform markdown editor with pdf export.

[drjwbaker]

My idea is that dillinger is not a permanent solution but much much easier than enforcing pandoc. Is people have other ideas, great!

[drjwbaker]

See Shell lesson as potential model to build on https://github.com/data-lessons/library-shell/issues/34

[drjwbaker]

Discussion of potential alternatives at https://github.com/data-lessons/library-shell/issues/34 Consolidate discussion here.

[gvwilson]

We can automatically generate a handout from the key points listed in the header of each episode to create a printable page (and then use conditional CSS to format it differently if so desired) - see https://gvwilson.github.io/handout-example/handout/ for an example of what would be included for the example lesson.

[drjwbaker]

@gvwilson I found yesterday, however, that I can't put regex in keypoints as it breaks the formatting of the header.

[drjwbaker]

(or indeed any shell code)

[gvwilson]

Should be fixable (probably just using the wrong escape pipe) - can you please file an issue in the lesson example repo and we'll ask @rgaiacs to find a solution?

Assuming it's fixable, is a keypoints-based solution acceptable, or are there other things a handout would need? Diagrams immediately come to mind...

[drjwbaker]

@jt14den Do you still intend to raise this issue as discussed in handover?

[jt14den]

@drjwbaker didn't have time to yesterday, but will now. I wanted to see what it was doing locally first.

[jt14den]

@drjwbaker I can't replicate the problem. I added some of the regex expressions from the 03-free-text.md episode in library-shell. I also added one grel expression with a regex from open-refine. I pushed them up here: http://www.tim-dennis.com/library-shell/03-free-text/

Is there another regex that you were working from that didn't work?

[drjwbaker]

@jt14den Huh. That is odd. My bad. I'll take another look.

[rgaiacs]

@drjwbaker I think

- "Shell tools can be combined to powerful effect"
- "sed -e 's/<[^>]*>//g' diary-noheadfoot.txt > diary-notags.txt"
- "tr ' ' '\n' < diary-clean.txt | sort | uniq -c | sort -r > diary-final.txt"
- "tr -d [:punct:] < 000003160_01_text.json > 000003160_01_text-nopunct.txt"
- "tr [:upper:] [:lower:] < diary-notagspunct.txt > diary-clean.txt"
- "`tr ' ' '\n' < gulliver-clean.txt | sort | uniq -c | sort -r > gulliver-final.txt`"
- "value.match(/(.*),(.*)/)"

doesn't help the reader since is just commands without any information about what they do.

The only two issues that I could spot are

1. tr ' ' '\n' < is tr ‘ ‘ ‘ ‘ < on the HTML
2. "`tr ' ' '\n' < gulliver-clean.txt | sort | uniq -c | sort -r > gulliver-final.txt`" should be "tr ' ' '\n' < gulliver-clean.txt | sort | uniq -c | sort -r > gulliver-final.txt"

[drjwbaker]

@jt14den See https://github.com/data-lessons/library-data-intro/blob/gh-pages/_episodes/04-regular-expressions.md "[] defines a range of characters" breaks the header :(

[drjwbaker]

@rgaiacs The sort of info we'd want in the handout - so expressed via the keypoints - are the lines at http://data-lessons.github.io/library-data-intro/reference/

[drjwbaker]

(I agree what you have above doesn't help the learner. What we want is a cheat sheet)

[drjwbaker]

Fixing this now so the broken header doesn't stay up. This https://github.com/data-lessons/library-data-intro/commit/a53951045c100da66795f37e92b418eb2084c003 is the formatting of the header with "[] defines a range of characters" that breaks.

[jt14den]

@rgaiacs that was just for testing purposes, not what we want as @drjwbaker indicates. I was trying to find what breaks the template.

@rgaiacs see above. It looks like [] breaks the header. I can try it soon and make an issue.

[jt14den]

@drjwbaker and @rgaiacs it's not the [] that breaks the yaml bullets. That seems to work fine. I think that it's the sub-list @drjwbaker was trying to make by using

- "Regular expressions are powerful tools for pattern matching"     
-- "`[]` defines a range of characters" 

That breaks the keypoints. It will also break if you use the github markdown way of creating sub-lists (two spaces in)

- Regular expressions are powerful tools for pattern matching       
  - "`[]` defines a range of characters" 

@drjwbaker are sub-lists essential in creating handouts? If so, anyway of making that possible @rgaiacs ?

[rgaiacs]

@jt14den YAML supports two syntax for lists. The first one is

fruits:
    - Apple
    - Orange
    - Strawberry
    - Mango

and the second one is

fruits: ['Apple', 'Orange', 'Strawberry', 'Mango']

The first one is "preferable" for aesthetic reasons. But the second allows you to have nested lists. You can also have nested lists with the first syntax but you need to use a "hack" as explained in StackOverflow.

I would suggest to avoid nest lists just because it should break the Liquid code that is rendering the key points.

[drjwbaker]

I wasn't trying to make a sublist. Just a list. As far as I can see I did not indent the text or use more than one "-". @jt14den: can you push an update with the line I tried to add please?

[jt14den]

@rgaiacs thanks for that info! @drjwbaker sorry! I mis-read the diff. You need to quote the keypoint if you are including regexes and other characters.

[jt14den]

Added the regex key point on the https://github.com/data-lessons/library-data-intro/pull/44 PR. It works! https://data-lessons.github.io/library-data-intro/04-regular-expressions/

[drjwbaker]

I @jt14den spoke too soon :(

Right. I think it is backslash that kills the header formatting. See https://github.com/data-lessons/library-data-intro/commit/c8e49e09b706ee4a3827bc0078e7154495d10ecc. Having tested, I'm pretty sure it is the line..

"\d matches any single digit."

..that is the problem, and any line with a backslash in particular. Can someone else test and report back please?

[alexandermendes]

Looks like you've figured it out already but you can just escape it with a double slash!

"\\d matches any single digit."

[drjwbaker]

We have a winner! I hadn't figured that out, so thanks @alexandermendes!

[drjwbaker]

It works! Man this template is a faff sometimes.

Next step in managing handouts, how do we propose turning http://data-lessons.github.io/library-data-intro/reference/ into a nicely formatted handout?

[rgaiacs]

@drjwbaker I didn't tested but you could try replace https://github.com/data-lessons/library-data-intro/blob/gh-pages/_includes/episode_keypoints.html#L8, i.e.

    <li>{{ keypoint|markdownify }}</li>

with

    <li>{{ keypoint | escape | markdownify }}</li>

[jt14den]

Sorry @drjwbaker for closing too soon. Thanks @rgaiacs for the markdownify approach.