The lows are low, but the highs are home
Month
In my last post, I mentioned that exporting from Org was a big reason for using it to present. I personally feel like video content is a complete waste of time, so I definitely want my presentation to be available in a format other than video. Because it’s been around for a while, I had read in a few places about slideshows using S5. And I knew that it was possible to export to S5 from Org (note: old info). Surely this would be easy and the output would be perfect on the first try! That turned out to be the exact opposite of what happened. In the end, it took at least five or six hours of fiddling in order to get everything working. Admittedly, if I knew more about HTML and CSS - in other words, if I were the sort of person S5 seems to be designed for - it would likely have been much easier. Likewise, the most up-to-date export tool, ox-s5, seems to be aimed at people who already know a lot about S5. Maybe you can see where this is going.
Rather than rant about how I stayed up until 2am the night before (or the morning of?) my 21st birthday messing with HTML in a text editor, I’m just going to list off a bunch of lessons I learned, to hopefully save future users a bit of pain.
The first issue is the customization variables that ox-s5 offers. Don’t use ‘em. I know, we wouldn’t use Emacs if we didn’t want to change settings - but no. You don’t want to change these settings. The only one you’ll want to change is to specify your theme file, and while there are many wrong ways to do this (and I tried them all), the right way is to specify a CSS file. The exact filename depends on the theme you’re using. For me, I used (setq org-s5-theme-file "railscast/pretty.css"). That’s a relative link, which were the only kind I could get to work, to the railscast theme from the org-s5 repository.
The setting that really messed with me was org-s5-ui-url. It doesn’t seem to do anything other than break your slideshow. I tried settings a direct link to the ui folder, as in C:/Users/Matt/s5/ui - didn’t work. Perhaps it was being interpreted as a relative link, I don’t know. Given that I had no idea what I was doing, I spent a while re-exporting my slideshow, opening it in one folder, moving it and opening it in another folder, over and over in a pitiful attempt to make things work.
When I stopped customizing this variable and reset its value to ui, all of a sudden I had a semi-working presentation! The HTML file has to be kept beside the S5 ui directory in order to work, but whatever. Also note that the ui directory has to contain both the theme you want to use and the default theme, as most themes seem to reference the default theme.
Once I had something being exported, the first thing I changed was to tag parts of my Org file as :noexport:. Just write that beside a heading, and it won’t appear in exported documents. Useful for embedded code blocks that you use to process results and such.
After this, I needed to tweak exported HTML file, which is unfortunate. Most of the changes I made could be automated, if I knew enough Emacs Lisp; for now, perhaps some kind soul will incorporate them into ox-s5. So, what did I change?
I deleted the table of contents. org-present considers every top-level heading as a slide, and nothing else (this is kind of annoying). ox-s5 exports a table of contents containing every heading in your file. These two facts don’t play well together, because org-present encourages having a lot of headings, which then gives you a TOC that’s too large to display on one screen. Aside from that, the table of contents doesnt’ even provide links to specific slides, and S5 advances slides when you click, so it’s useless twice-over. Would be nice if there were an option in ox-s5 to turn off the TOC.
The next issue is that some part of the exporting toolchain considers the underscore character as a marker for subscripting. So if I mention, in plain text, a function called waste_time, I get wastetime in the HTML output. It’s hard to say if this is a bug, a misfeature, or what - at any rate, I had to regex replace <sub>(.+?)</sub> with _\1.
I didn’t like the section numbers being beside my headings, so I removed those. Regex replace <span class="section-number.+?</span> " with nothing (trailing quote mark intentional, I think). Unsure if this can be customized already, but it would be nice to have a choice.
In a few cases, when a slide got too long to show on my (admittedly small) laptop screen, I had to add an extra <div> around half the content, and specify class="slide". For a few of my headings, I also deleted the slide class, so that S5 would skip over them. If you know as little about HTML as I did at the time, that’s probably hard to visualize - so check out the source to see what I mean.
The exported HTML has some CSS embedded in it, and I tweaked things there rather than modifying the theme file (at least, originally - some things are in the theme file now). First thing: When you have code blocks in your source, ox-s5 will show the programming language name when you mouse over them. Only for a few predefined languages, though - and it should really decide what languages to use based on org-babel-load-languages. I added this rule: pre.src-python:before { content: 'Python'; } to handle Python blocks. Also, the language name doesn’t show up very well on dark backgrounds, so I added color: black; in the existing pre.src:before block.
Another issue I was having was that using the arrow keys to change slides was attempting to scroll the page. So the scroll bars would show up, sometimes content would go off screen in certain browsers if you pressed left/right too much, and it just looked dumb. Adding body { overflow: hidden; } fixed that. This probably deserves to go in the theme file itself, but perhaps ox-s5 could specify it anyway - I can’t imagine why you’d want the scroll bars visible.
Lastly, for aesthetic reasons, I decided to center my headings. So: h1 { text-align: center; } and h2 { text-align: center; } handled that. However, that made my title slide look weird - apparently my theme added some padding to headings. Solution: #slide0 h1 { padding-right: 0; }. This isn’t useful for anyone not using the railscast theme, but since it’s the only good looking theme I could find, I figure it’s worth mentioning.
S5 also has some funky JavaScript code, pre-jQuery, which attempts to hide slides other than the one you’re currently looking at. For my presentation (which had some short slides), and with the theme I was using (which didn’t have large a large header or footer like the default theme), this wasn’t working all the time. Oddly enough, sometimes it would work, for a little while. Anyway, there was no need to fix the JavaScript portion - adding .slide { margin-bottom: 1400px; } solved the issue.
As a bonus, it also fixed the problem I was having where slides at the bottom of the page couldn’t be shown correctly. Presumably, this won’t work perfectly on screens taller than 1400 pixels + length of my content, but I don’t know how big of a number I’d need to use to satisfy people with vertical monitors. This might be worth including in ox-s5’s output by default - I have no idea if it has any adverse effects, though.
Edit: Turns out adding this bottom margin globally messes up the print stylesheet, which would have allowed me to easily convert the slideshow into a PDF using Chrome’s print to PDF option (and presumably other browsers can do it too) - without the pain of exporting from Org to LaTeX. With the margin, each slide winds up being on one page when you try to print (if that’s what you want). Normally, the settings for printing are in a file called print.css. If you put the margin-bottom thing in your main theme file, in my case railscast/pretty.css, it works out fine..
Edit 2: If you scroll using the mouse with the margin active, you wind up in empty space. And the arrow keys stop working. So, uh… don’t do that.
And after all that, I finally had a working slideshow. You can see it here, if you want. I realize that these instructions are probably fairly specific to me, but, if I want to make another slideshow in a few months I’ll be happy I wrote them down. And I guess I did learn a bunch about CSS and HTML from a supa pro web dev friend. It was painful at the time, because nothing worked and I had no idea why, but I’m happy with the end result and happy with what I learned.
…However, while preparing this post, I found org-reveal. Which kind of sucks because it looks amazing. Probably because Reveal.js is more modern, org-reveal offers more control over the structure of the exported presentation, to say nothing of the options for visuals and other fancy junk. I mean, I like the look of my presentation - I’m a minimalist. Which is to say I have no sense of design whatsoever and the less design involved, the better. But the setup of S5 means that nice things require editing HTML and CSS, and I know neither. I have no idea how I’d add transitions between slides, for instance. And I can’t specify those things in my Org buffer, like I could with org-reveal.
In other words, this is probably the only time I’ll ever use ox-s5. But I’m glad it exists. The one downside to Reveal.js is that I think it’s what everyone else uses for their presentations at EdmontonPy, and it likewise only has one good colour theme (the default), so if I had used org-reveal there would have been three nearly-identical slideshows in a row. That just seems weird to me.
For the more visually inclined (not me), impress.js exists, and there’s an older package for using it from within Org. It hasn’t been updated for Org 8’s new export engine, though, and since it’s 3000 lines of code, an update could be non-trivial.
Considering I understood decorators before starting the presentation, I didn’t do a lot of research in terms of “learning new stuff”. What I mainly needed were code samples and practical uses, to make a bit of an argument for using decorators at all. So the research was mainly just reading a bunch of articles online and being sad when the coolest one - automatic timeouts for potentially long functions - wouldn’t work on Windows.
No, the real fun part of preparing the presentation was the software side. I decided pretty quickly that if I was going to give a presentation to a bunch of programmers, I may as well show off a bit - so I’d do the presentation in Emacs. If I used Org mode, I could then export the presentation to a wide variety of formats, theoretically with very little effort. I had found a few packages via ELPA for handling presentations (I have a terrible thing for periodically reading the full list of available packages). Sacha had some information on her blog, too. I settled on org-present, because it was simple enough for me to understand as an Org-mode beginner, without preventing me from editing on the fly.
org-present worked flawlessly, so I don’t have a lot to say about it. Though I do wish it could step into some second-level headings (something like Sacha’s code, which I think uses tags, would be more flexible).
The other fun part of this equation was Org Babel - a built-in part of Org that allows you to execute code snippets and embed the results in your document. It does some other neat things for literate programming, which seems cool, but that’s beside the point. The one little thing about Babel is that, normally, you use it to execute the code snippet that your cursor is inside. Because org-present uses narrowing, I knew that each slide would only have one code block, and I didn’t want to manually move my cursor while presenting. Solution: a macro! Incremental search for an opening parens, hit the keys for Babel execution, and switch to an output buffer. I was pretty happy when I got it working.
One small issue with Babel is how it interacts with the Python interpreter. It’s not bad, it’s just… surprising. Babel lets you create an ongoing, dedicated interpreter session so that variables and functions can continue across multiple discrete code blocks. If you don’t do that, everything works the way you’d expect. If you turn it on, suddenly you may get errors due to invisible whitespace and other dumb junk. If you use the session argument and the :results output option (basically, give me whatever the interpreter prints), you unfortunately wind up receiving the interpreter’s prompt and some other junk in your results.
Luckily, a recent addition to Babel allows you to set a function or block of code to perform post-processing on your results. So I wrote a bit of Emacs Lisp to do a regex-replace of “>>>” (the default prompt) - check the org source in the presentation repo if you’re interested.
Also, if you’re using fgallina’s python mode (the default as of version 24.3), I’d also recommend not editing code directly within your Org buffer - use C-c ' org-edit-src-code instead. I had an issue where it would continually indent my code, causing the interpreter to spit out errors,and various other buggy behaviour - and it worked fine if I used org-edit-src-code. So do that.
I know that doesn’t sound like a whole lot of fun. And why didn’t I just make a slideshow like a normal person? Here’s a few completely biased reasons for doing things this way:
So I’ll admit that those aren’t convincing arguments for why anyone else should present in Emacs, but it’s good enough for me. And you really can’t ignore the emotional value of having a slideshow that didn’t involve PowerPoint.
As for the presentation itself, I think it went reasonably well. There were some technical difficulties, which have are on tape for all of eternity. I had about 30 minutes allotted, so it was basically just me talking at the audience and hoping it stuck. Speaking of which, it was a smaller group than normal, because PyCon Canada was at the same time. I think there was a decent mix of experience levels - some very experienced, and at least two early year undergrads.
I would have liked to interact with them a bit more, take more questions about what was or wasn’t making sense - but that’s what tutorials are for. I didn’t spend a lot of time going over the code, but much like the professors who page through slides faster than you can take notes, I knew they could look up the slides later. And I have links to all the stuff that I read to learn about the topic, so there’s that too. I included a couple of plugs for Matt’s book, for obvious reasons. If anything, the best thing I could do is convince them to read that.
Hmm, what else. One person asked me about how I did the presentation in Emacs - I’ll talk more about that in another post. A professor in the computer science department at UofA congratulated me on doing it in the first place, and we chatted about his experience doing live coding. I saw him at a PhD thesis presentation later in the week - hilariously enough, he has either the same laptop as I do (the tablet version, too) or the model from the year prior. I’ll probably write up some notes about that presentation, but, that’s a tale for another time.
I thought the meeting started at 6pm, but it was actually 6:30. On the one hand, that gave me enough time to eat at the pub next door. On the other hand, that gave me just enough time to eat at the pub next door. I walked in, asked if they could prepare anything in 15 minutes, the waitress said yes, and it turned out she was right. During a brief moment of sanity, I started by eating the fries first, but it didn’t last - I tried to eat the burger as fast as possible, and in the process, thoroughly burned most of my mouth. I didn’t feel it until afterwards, but, when I did - ow :(
I got really stuffed up for the next few days, which was really annoying. I figure it was some sort of ineffective response to my burned mouth, but who knows. It kept me from talking to the CS professor when I saw him again, because I didn’t want to make anyone sick. I’m not even sure I was sick, except for one day where I felt terrible. Anyway, I’m sure you don’t care about my suffering. I just wanted to write it down while I still remember.
It’s pretty hard to believe that the entire summer has gone by, and I’ll be coming home in less than two weeks. But before that, I did something brave! On Monday, I went way outside my comfort zone and gave a talk at EdmontonPy, the local Python user’s group. The talk was about a specific metaprogramming feature in Python called decorators. If you know what that means, or think you’d like to know, you can check out the project page on GitHub, or jump straight into the GitHub repo for extra goodies.
Anyway, I’m not going to reiterate the content of the talk here. The text is online (I even edited a lot of things after the presentation), as is a rough version of my script, and a recording is on YouTube. That basically covers anything anyone could want. I just thought I’d write up my thoughts about the experience.
Towards the end of June, I started wondering whether I should invest more in my programming skills. I was already learning a lot at work, by necessity, but I thought I could be doing more. I searched for “Ottawa Python”, and found Ottawa Python Author’s Group. Obviously, I then checked to see if there was anything for Edmonton - and there was! So I tentatively decided to attend the July meeting, and managed to follow through on it, too (though I came close to turning around a couple times on the way there).
I enjoyed Daniel Nephin’s talk on itertools, and Aden Grue’s talk about Unicode brought up the one or two Unicode pitfalls I was lucky enough not to trip on already. I chatted for a bit with one of the primary organizers, Brian Forst, who also works at the University of Alberta. While I hadn’t asked my supervisors for permission yet, I’d also gotten particularly excited about the idea of going to PyCon Canada. I asked around, and was directed to (I think - correct me if I’m wrong!) Diana Clarke who has been involved in organizing the most recent PyCons. We chatted for a bit about the conference, and she more or less suggested that I might want to wait until next year and apply for funding of some kind. Didn’t matter in the end, though, because the timing was bad (my supervisors would be getting back from month long trips at the same time).
Anyway! So that was all well and good. As I was walking back to the subway station, obviously inspired, I started reading an ebook I’d bought called Guide to: Learning Python Decorators by Matt Harrison. I got the ebook on Amazon fairly cheaply, but I won’t link it ‘cause he deserves a larger cut of the sales. It’s concise, the writing is clear, and organized beautifully.
It’s laid out in such a way that concepts many people struggle with learning - functions as first class objects, closures - seem to just follow naturally from the content of the previous sections. Even though the majority of the book isn’t literally about decorators, the earlier sections make them much easier to understand. Plus, it turns out that closures are pretty simple and they’re actually really useful.
In other words, there may never be a better explanation of decorators than Matt’s book.
Despite the high quality of the book, upon getting home and finishing the book (it’s no longer than it needs to be), I decided I could probably give a talk on the subject. I must have known at the time that I couldn’t possibly present the topic as well as the book had, but I felt like stretching my boundaries, so I sent off an e-mail volunteering to give a talk in August.
I promptly got an e-mail back saying they already had two talks scheduled, but they’d keep me in mind. They had announced the talks for August, right in front of me, and apparently I forgot five minutes later. Oops. But then a few weeks ago I got an e-mail saying the original presenter was too busy to prepare a talk, and they were looking for volunteers. Woo!
Anyway, I’ll post shortly about how it actually went, and then after that will be a bunch of technical notes that will, some day, show up as search results for the people as frustrated as I was when I prepared my presentation.