Well so beeminder is telling me that I owe them $10 unless I write something today, which means that I really need to get those technical posts out of the way that I’m working on about papers I’m reading and some of the research-y ideas that are stewing around, but at least for today I’m going to postpone those moments of vulnerability just a teensy-bit longer by writing more various teaching projects I’m working on. This is basically several smaller posts tangled together into a long ramble, so bear with me.
I wanted to talk about those aspects a little bit for those of you who aren’t super nerds for org-mode. You can include, in your documents, source code just by typing “<s” and hitting tab and then it expands into the src block as follows
#+BEGIN_SRC language-name :exports what-you-want-to-export :results type-of-output #+END_SRC
You can then edit the source code by typing C-‘ with the cursor in the block and it sends you into a temporary buffer that is in the proper major-mode for that language. For example, to format the block of code above I included it as a src block of the type
org and I could then still use org-mode shortcuts to make the literal example of an org-mode file. So. Meta.
We can also run our source code by typing C-c C-c within a source block. For example, in the following code example, which looks like
#+BEGIN_SRC js :exports both :results output var thingy = 10; console.log(thingy*thingy); #+END_SRC
we can see that it prints out the results of the program beneath the source code
var thingy = 10; console.log(thingy*thingy);
and after evaulation the actual block of org-mode source looks like
#+BEGIN_SRC js :exports both :results output var thingy = 10; console.log(thingy*thingy); #+END_SRC #+RESULTS: : 100
I’ve found this very useful for writing exercises since I can have the solutions right there in my .org file that aren’t exported but I can still test to make sure that they work correctly. I also make a habit of testing all of my examples as much as possible as I’m writing them, which both helps me avoid the embarassment of giving students examples that don’t work and helps me double check that I’m understanding the language correctly.
Now being able to write and run the code is nice, but what’s really great is being able to extract source code chunks to an actual file. You do that with something like the following
#+BEGIN_SRC js :tangle test.js console.log("this file doesn't do anything interesting'") #+END_SRC
and then when you hit C-c C-v t the source blocks are all extracted into files. Also, something I didn’t understand at first that led to an embarassingly confusing bug is that if you have two different source blocks with the same :tangle name then they’ll be concatenated.
I like writing tutorials with all of the code inline and files generated by tangle because
- I want to encourage literate programming
- It helps me organize my thoughts
- It prevents duplication between source in the text and the real source files
- I think tutorials work better when all the moving parts are in plain view
The last one is about a serious pet peeve I have when code offered in tutorials or papers is “morally correct” but is actually a simplified version of what really works. If you’re experienced, of course, you can spot what’s really needed but if you’re a novice you can tear your hair out wondering what you’re missing.
The final thing about my org-mode workflow lately is that this means that I can very easily export to HTML or markdown (which is what all three of us in this course have implicitly agreed to use) by just typing C-c C-e and picking the right options from there. It’s so convenient.
Maybe this all seems a bit silly to gush over, but I so appreciate being able to easily format my writing well.
The final thing I wanted to mention is that I, similarly, have a github repo for my theory of computation course https://github.com/clarissalittler/cs311 where I’m storing my lecture notes, the assignments, and any other supplemental things that I think are useful. It’s a pretty similar workflow where I have a number of .org mode files that I’m using to generate as much of the material as possible. The main difference is that it’s exporting to pdf via latex at the moment because I figured having a pdf would be a convenient way to read 60 pages of lecture notes. I’m going to actually point my students this fall to the repo for the course because it seems like a really easy way to distribute materials and, potentially, get students to flag typos or clarifications in the lecture notes or homework using the issue tracker on github or even by fixing little things themselves and making a pull request. How great would it be to actually get student help each term in making your lecture notes better?
I think that might be everything I wanted to brain dump today. That was kind of a lot.