Back to the schedule
Previous: The use of Org mode syntax outside of GNU/Emacs
Next: Babel for academics

Using Org-mode to teach programming

Daniel German

CategoryOrgMode

Q&A: live Q&A or IRC
Duration: 20:49

If you have questions and the speaker has not indicated public contact information on this page, please feel free to e-mail us at emacsconf-submit@gnu.org and we'll forward your question to the speaker.

Talk

Q&A

Description

In this presentation I will explain how to use org-mode effectively to prepare teaching materials, and how to present them.

For the last 5 years I have been using org-mode to teach programming in different languages: C++, SQL, Ruby, Python, SML and Scheme. Org-mode has three key advantages:

1. it supports most programming languages with a common interface,
2. it is an interactive medium for delivering teaching materials; and
3. it is an always-up-to-date format that does not need to be exported in order to be published.

I explain how I use org-mode in my courses and how I combine org-mode notes other tools such as github org-mode to get always up-to-date teaching materials that one can use for both teaching and studying (see https://github.com/dmgerman/csc116ModernCplusplus/blob/master/lectures/l-01-1-intro/01_1_intro.org for an example).

Finally, I will discuss some important aspects to consider when using org-mode for this purpose.

Discussion

IRC:

• how do you keep the discipline of working on your notes? that's probably my biggest problem
• I like "Try that with PowerPoint!" as a new org-babel slogan
• we just need krita and inkscape modes
• i remember doing similar in Smalltalk using a presentation tool with in it but with a full on graphical display of the Smalltalk environment not just text based.
• I liked the trick with annotating the code in xournal -- what is the elisp glue for that? Do you have a package for that?

BBB:

• Can you talk about how the students re0act to this org-mode approach?
• What level are your students typically? what is the subject matter?
• Why GitHub? GitHub is nonfree.
  • Perhaps because gitlab is also there and that there is achoice?
  • GitHub requires reCAPTCHA to signup and similar things that are free exist (various GitLab and Gitea servers, Savannah, sourcehut).
  • GitLab.com is just as bad (and unlike GitHub, you can't sign in without nonfree JS), but GitLab CE is fine.
• Do you think org-mode+git could be used for students' assignments?

From YouTube:

• this is by far one of the most motivating talk about Org. I feel sorry about all my teaching colleagues that still use WYSIWYG presentation tools. my life, as a trainer, literally changed with Org, even without literate programming.
• Great presentation. New to Emacs and starting to find many uses for it. One thing which theme you are using

Outline

20 minutes:

• Introduction
• Quick demonstration
• Workflow
• Some Important considerations
• Emacs configuration and how to get started

I have create a git repository with examples and config files that is ready to use: https://github.com/dmgerman/teachingProgOrg

Transcript

Hello, everybody. My name is Daniel German. I'm a professor of computer science at the University of Victoria, and I have been teaching programming for more than 10 years. I want to tell you today about how I have been using Emacs effectively during the last 10 years, and to try to improve how I not only create content for my students, but also how I deliver it, and particularly how, within the last five years, I have been using Org mode in a very effective way that benefits both my students and myself in the creation and the delivery of content. Let me switch to my computer. I'm going to remove myself because I can use all the real-estate screen.

[00:00:51.840] The goal of my presentation today is really to give you a little bit of an overview of how I have been able to combine the use of Org mode and with some other tools. I'll talk about specifically about them and then also offer some suggestions and recommendations in how to get it started. I have created a configuration, a set of configuration files that you can use. I will describe them towards the end. Hopefully, it will make it easy for all of you to get started on using it. So we start talking a little bit about the challenges of teaching programming. I think that the fundamental one is that keeping the content and the slides up to date is hard, because the content is programs. There are programs that sometimes have errors, and sometimes the slides are incomplete snippets of code, and that once they go into the slides software, like Google Slides or PowerPoint, they're essentially static objects. If we need to update them, we basically don't know whether the update code actually works, or does it work? Also, we cannot insert automatically the output. We'll have to run the snippet outside, and run it, and then insert that code. So that's very cumbersome. It's really, really one of the major challenges of using a slide software to teach programming. The other thing is that during the presentation, there's nothing you can do with the code. You might be able to edit it, but you cannot run it. You have to move outside of the presentation software to be able to execute the code. The last one is kind of related to the previous two. You don't have a single file and your information is spread across many, many different files, especially if you have lots of different snippets in your slides. You probably have a lot of different small files, each of them contributing something to your slides, and so it becomes a pain to manage. All of this is where Org mode really excels. Org mode is capable of doing everything, and it needs a little bit of help from some friends. I will describe what I mean by that. But the other thing that is also very valuable is that it's within the magic of Emacs. I absolutely love to be able to work with text within Emacs. I enjoy actually creating my notes in Org mode way more than if I was making them in Google Slides. Let me start by giving you a short demo. I have been teaching programming in C++ for around five years, and this was really the trigger towards trying to do everything within Org mode. So I have a repository in GitHub, and I think that GitHub is an excellent tool that works collaboration with Org mode. I'll describe actually what I mean by that. My lectures are essentially Org files. So, for example, let's go into one of these files. This is a an Org file. You can actually see it in the extension. I get a table of contents. GitHub creates or give us actually the ability to quickly jump, and it creates a dynamic table of contents, but I also can actually create it automatically, and then here it goes. This is the code that i have. This is a snippet that I present in the class. Let me actually show you how I do it within Emacs. So what I will do is the following. Let me try to open that file. Here's the file, and it's exactly the same that we were browsing in GitHub. What I do is I simply just scroll through the document. It's almost like movie credits at the end of the movie. I don't break them into chunks that I show in the screen. I see no point in doing that. What I do is I simply scroll through the text. The students are able to see the same information in GitHub on their computer, or they can print it if they want, and they are able to actually follow with me, and then having a much bigger picture than if i just show a very small snippet. In the case that the snippet is too big, for example, let's say this one actually doesn't cover the... covers more than full screen, I actually reduce the size and then give a little bit of an explanation of the whole thing, and then focus and say this is the line where we have to pay attention. Notice actually how I use color for that. I think that the ability to use color and typesetting is fundamental to be able to do this effectively, and the nice thing is that we can configure Org mode to be able to do most of this automatically. As I said before, one of the great advantages is that I can actually run the code dynamically. So let's say that the student says, "But what if I change that value to 10?" Well, let's try it. Let's change it, run it, and then you can see here that it has a 10. That's really powerful because you're not tied to what is the content you have on the slides. If you find an error or an omission, or you want to talk about something else, you can very quickly do it. You can add comments and then make some suggestions specifically to that, or worst-case scenario, if you really, really, need it, you can say, "Let's load it into..." Let's actually do some hand annotation. Let's actually say, "look at this thing, this is the value that I want you to concentrate on." It's not perfect. I'm not doing it with an Emacs. I wish there was a way to do it, but it is absolutely effective because I'm actually able to use the power. Notice that all that is exported is just the block, and also the color and typesetting, the typesetting of the content. So this is actually great. I have the colors red, purple, etc. etc. I love being able to do that. This is just a temporary file. I can actually discard it, and it doesn't really matter. Let me go back to the presentation. So that's the delivery. So the delivery is great, and I can tell the students now you're actually in GitHub, if you want to test the code, just cut and paste. Notice that I clicked on the little icon. Now it's copied. It's now part of the kill buffer (kill-ring), so if I want to actually create a file that has that content, I can very quickly do it. Try that with PowerPoint. You will have to have the text without any nice typesetting, or you will have to have a picture that is impossible to cut and paste. So that's something that the students really, really appreciate of this. They can try it on the computer. They can load it into their favorite editor. I don't force them to use Emacs, but I have to say that some of them really get intrigued by this power that they want to try Emacs because they see that they can do things, that I can do things that they cannot do with other tools. Okay, so let's go back to presentation. The other half of it is preparing the notes. I think the preparatory notes is something that I want to do as easy as possible. I want to be able to reduce the time that I waste on things, that they are done. They're not part of the actual thinking or the delivery of the presentation. So let me create a file. Let's call it rip2.org. Well, I have this one, so let's call it rip.org. Oh, I have this one too, so let's call it rip4.org. So it's empty. I use yasnippets. I think yasnippets are very important, and I'll go through this in a little bit later. It's important to set up the properties for each language that I use properly. I'll describe this a little bit later. Unfortunately, the properties have to be evaluated one at a time, and so I'm just going to kill the buffer and open it again. So now all of these properties are properly set. As I said before, I have some yasnippets, so I can actually do very quickly... This is C++, cout << "hello world", std::endl. And then I run it, and then it's inserted down here, so nothing special. Let's assume that I make a mistake and I type a double l here. I will get an error. These line numbers unfortunately don't perfectly match with the line numbers in the little snippet because there's some code that org-babel inserts, so that shifts them. So that's something to be aware of. I can correct it, run it, and then it inserts the result. Let's do one in C. I'll explain the exports both a little bit. So let's assume that I don't want to have a full main program. Let's assume that i just want to demonstrate how to use a printf "hello world %s\n", "my friend". Let's run it. I get a bunch of errors. Why? Because I don't have a main program, so I have to actually tell org-babel that I want a main product, so yes put a main around it. So now I run it and it says, oh, in the function main, we have an implicit declaration for function printf. I'm very, very stringent on my compilation options, so I want to have every single potential error displayed , so that's actually why. In this case, I actually need include, so I can say :includes <stdio.h>, and I'll run it and it runs perfectly. So why is this important? Well, it allows me to just have the snippet that I'm concerned about. I don't have to have all the overhead of having to have the include, main, etc., if I want to show just one specific concept and I can do it in very few lines of code. I can do that immediately, of course. The students will not be able to cut and paste it without the main file, but that's something that we can explain to them. We can do all the languages. So I can say print, let's print just a list, or let's actually keep updating it, and let's do a map of a lambda x, x multiplied by x, and then we run it. Okay. The thing that is important is that if we also have the full power of the environment, right, so we can actually edit it in the native mode of the language, and wherever we actually want to use specific features, that they are available in the particular mode. But for most of the cases, I don't need that, because my examples are relatively simple. Let's do one more. This is a little bit different: SQLite. In the previous examples, the output that is inserted is a standard output. In SQLite, I want to actually see the tables. I want to see how the tables are, what the results are. So let's create table s. Let's call it r, a int, b int, and let's run it. This is-- oh, the table already exists. Okay. So drop table if exists r, and then we run it. Okay. So now it's created. sqlite... So we can say create a table, and let's actually add SQL, and here we're actually going to add... This is an example in C, and here we're going to have C++. Okay. So, SQL, and then we create a table, and then we populate and then insert into R values 1,2 2,3 3,4. Okay. So now I have a table, I have values, and I can do "select * from here," and then I get the result. Okay. It's almost magic because I can actually get, formatted, the output in the way that I expected. Obviously, if my result is too big, then it will basically just create a huge, huge buffer, or Org will say the output is too big. So often with databases, I actually narrow my output, right, or I might do it with a clause, "where a > 1". If the language is supported by Org Babel, then you can do all of this. Let me go back to the presentation. I'm running out of time. Let me give you a short tour of how this is done. I have created a repository that has all the configuration that I have. Everything is self-contained. You can just download it and run it. You will have to replace your ~/.emacs.d directory, and then you can explore it, test it, and then pick things out of it, choose, etc. Let me go through the README. I think that the README is actually useful. I have a function called actually start. That is the one that creates indentation and sets up the mode, etc. Let me talk about GitHub. So GitHub is a great resource. Why? Well its publishing, as i mentioned before, is very simple. To publish, you basically just push your changes and it automatically renders the code. It's something that is quite useful. But it is not perfect, and it's not able to understand the full Org. But for most of the things that I use for teaching, it's sufficiently good. It would be better if it was full at compliance, but it's not bad as it is. Version control. I think it's extremely valuable to have version control. It allows to actually use different computers or keep track of my changes, collaborate with authors, even have pull requests from the students. Actually it's very empowering for the students. Navigation, links, cut and paste between code blocks, you can even edit in place if you want to. In a pinch, you can actually use GitHub to do the editing of your file. Of course, it will not update your buffers. :exports both. This is very important. If we have a block, by default, GitHub will not typeset the output of that block. It will only put the source code, but not its output. In this case, if I actually showed this in GitHub, "hello world" will not appear. So what we need to do is for every block, we have to do :exports both. okay that's unfortunate, but we can deal with that. Once it's done, then the output is actually typeset. I mentioned that header args are very important, because those are the ones that set the parameters for each one of the blocks that you have. You don't want to have to type every single one of them at once. For example, let me go back to my presentation. Here's actually the parameters for C. C, I say, I don't want you to automatically add a main. I want to provide my main, and these are the flags to the compiler. With C++, similar. With SQLite, I said this is my database, this is the data, the file where the database lives, and for the results, I want you to insert the column names. I want to see the names of the columns in the result. So those are actually why the headers are important. There's one in general. That's :results output. If you're interested on showing the standard output of your snippet, then you have to use :results output. Otherwise, it will insert the result of the last expression. It just depends on what you want to show, but it's important that you are aware of that. I'm almost running out of time. There are some things that are C-specific and that I sort of covered during the demo. You can use advanced Org features, and you can actually use noweb. Now that's confusing for students, so i will suggest that you actually do it but then inform the students very clearly of that. Some potential issues: _ (underscore). _ is used everywhere. By default, it will try to export it-- Org will try to export it as circumflex, the same as with GitHub. So we want to inform Org and GitHub not to do anything with them, and this is via the circumflex. So we said in #+OPTIONS: ^:nil , and that actually takes care of the circumflex and also the underscore. It's kind of confusing because it's both, but it's actually named after the circumflex. The pipe character is one of those characters that is actually very, very common in programming, but if you put in a table, there's no way to do it. Like, okay, I wish I had this table nicely where I can say || here, but if I put this ||, it will actually interpret it as the separator. So that's one of the few things that's kind of annoying. Final words. See my configuration file, and try to typeset the code, the buffer as close as possible to what you want to present. As you can see here, I'm actually using colors to highlight by using the current line. Use yasnippets. They're amazing, and they will actually make your life much more useful. Experiment. Just a conclusion. Org mode and Emacs really make a wonderful, amazing environment for teaching programming. I just want to end by saying that I'm very grateful to all the Emacs community because I have benefited tremendously over the years. I have been using Emacs since 1991, so this is essentially my 30th year that have been using Emacs. I think that is the most important, most fundamental tool that I use day-to-day, from reading email, to doing my teaching, doing my papers, my research... it's everything. So thank you all and I hope that you find this useful. Bye. captions by sachac

Back to the schedule
Previous: The use of Org mode syntax outside of GNU/Emacs
Next: Babel for academics