Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.
-- Donald Knuth, Literate Programming
This is a simple project, whose aim is to make it easy to create slides for talks about programming and source code.
Specifically, we want to write our slides as Markdown files which work with Remark.js or Deckset, and then use a code-generator within SBT to make sure your code examples compile.
The ultimate goal is to support literate Scala programming (from within a Markdown document), hence the name of this project.
While preparing for PNWScala I realized that it would be nice to make sure all my code examples compiled. I also wanted to easily load my examples into the REPL to play with interactively. I decided that it would be easy enough to generate valid Scala source files by transforming the Markdown slides.
(You might also recognize building a general framework to support writing slides as a clever way to procrastinate on writing slides. Guilty as charged.)
You should easily be able to fork this project to help prepare your own Scala slides.
The expectation is that you'll want to fork this repostiory and start editing it for your own talk. Here is a handy step-by-step guide of what you can do:
- Edit
build.sbt
to add any library dependencies you need. - Create your slides:
- Slides should go in the
slides/
directory. - File names should end in
.md
. - (This is the time-consuming part.)
- Launch SBT
- Run
render
to construct HTML slides
- Every
xyz.md
file is transformed intohtml/xyz.html
. - Open these HTML files in your browser to start a presentation.
- Run
compile
to compile your code.
- Generated code for
xyz.md
is located atcode/xyz.scala
.
- Run
console
to launch a REPL:
- Every
xyz.md
file is translated to anxyz
object. - Use
import xyz._
to import methods fromxyz.md
- Top-level code will run when the
xyz
object is referenced.
(Eventually, it might be nice to support this kind of code-generation via an SBT plugin. If that's something you're interested in working on, please get in touch!)
I got interested in this whole workflow via Deckset, which makes it easy to create really excellent-looking slides from very simple Markdown files. Despite being a closed-source application, I was prepared to admit that it was better than anything else available.
However, I'm really not happy with Deckset's ability to syntax-highlight Scala. Since it uses highlight.js I figured it would be a simple matter to patch that library and improve my slides. (And in fact I did so.)
However, Deckset does not give users the ability to define (or
improve) syntax highlighting support. And due to Apple's ridiculous
application-signing, it is impossible to manually-patch
Deckset.app/Contents/Resources/highlight.pack.js
with a custom
build. Ugh.
Fortunately, remark.js seems to make it just as easy to define slides, and while the text doesn't end up looking as nice as in Deckset, the code examples are waaaay better.
All code is available to you under the MIT license, available at http://opensource.org/licenses/mit-license.php and also in the COPYING file.
Copyright Erik Osheim, 2014.