Back to the schedule
Previous: Using Org-mode to teach programming
Next: Managing a research workflow (bibliographies, note-taking, and arXiv)

Babel for academics

Asilata Bapat

CategoryOrgMode

Q&A: maybe live (early morning in Australia)
Duration: 9:58

This talk was also streamed at an alternate time for APAC hours: https://libreau.org/past.html#emacsconf21

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

Download video, 9:58, 21.4M

Download .pdf
Download --compressed56.webm (13.3MB)
Download --main.vtt
View on Toobnix

Q&A

Download video, 5:19, 11.1M

Description

Plain org-mode is already an extremely powerful and customisable tool for task and time management, note-taking, calendar and agenda management, and much more. Babel takes org a step further by letting you write, evaluate, and export code in different languages from within a single file. In this talk, I will highlight some features of babel that I find exciting and extremely useful, particularly for an academic workflow.

Getting started with babel can be intimidating, but it's hard to stop using it once you start. As an academic, I typically don't manage large coding projects. My primary purpose is writing lecture notes, assignments, and papers, and managing related admin. Typically, I want to try and automate the boring portions of my workflow without extra overhead. I also tend to find various tasks easier in some programming languages and harder in others, and prefer to mix and match languages as the task dictates. Babel makes this process seamless.

A basic use case is writing a document in org-mode and exporting it to LaTeX or HTML. Org-mode even lets you write multiple documents in a single org file, which can be convenient. Babel lets you add all sorts of enhancements to the same file. For example, suppose we have a single org document with all the problem sets for a course. Within this single file, we could now:

  • draw pictures in ditaa, graphviz, or python instead of LaTeX,
  • use python to do complex calculations and then output the result as LaTeX,
  • define skeletons to quickly draw up assignment templates,
  • toggle exporting of assignments with or without solutions based on tags,
  • locally change export settings or run a post-export hook,
  • automatically export to LaTeX after saving,
  • tangle code blocks from some or all of the languages to external files.

I will try to showcase features of babel that academics could find helpful, by presenting some ways in which I have tried to use babel. I would also like to be inspired by other people's babel workflows!

Links

Discussion

IRC nick: asilata

Pad:

  • Q1: The talk was amazing thanks! I show the img inline in the Org file with org-toggle-inline-images, maybe useful to others too.
    • A: Thanks! I do that if I want to look at previews, too, but sometimes it slows down my document. Any tips for that?
  • Q2: I always tried to use Tikz for showing diagrams in Org Mode documents, but dot code blocks definitively make drawing graphics easier! Thanks for sharing!

From BBB:

  • Don't have a question, just to say inspiring to see how you use org-mode + babel. Thx!
  • Ha, a question, is your setup online somewhere?
  • Asilata Bapat: https://github.com/asilata/emacsconf2021
  • thanks so much for the presentation and sharing the details of your workflow
  • I particularly appreciated your "causal use" of skel :D

IRC:

  • the export-setup block is a great use case for orgstrap :)
    • asilata: I was just thinking that after the orgstrap presentation :)
  • Man I was just wondering how to write LateX in Emacs this is incredible.
  • I really liked the resulting LaTeX output file -- looked gorgeous :)
  • Yeah seriously. I am pleasantly surprised. I think I'll have to switch over to using Emacs and LateX
  • Theme: zenburn
  • wait ... does elisp support unicode lambda like racket?
    • I mean... you can make it, but not out of the box.
      • asilata: I think it's just an org prettification
        • prettify-symbols-mode
  • do you use latex preview in the org buffer too?
    • asilata: no, I usually don't, I find it slows down my system a bit.
  • some very nice examples of wicked-cool org stuff there :)
  • I also use python to generate latex from babel so that I don't mess things up

From YouTube:

  • Cool talk! I suggest to export your diagrams to some vector format (PDF, SVG, etc.) if you (as you say) embed it in LaTeX/PDF later. Otherwise, you can see blur on a large enough scale.

Links:

Speaker information

Transcript

Hi! My name is Asilata Bapat, and I'm talking about Babel for academics. So, I'm an academic at a university, and I use Emacs, Org mode, and Babel for a whole bunch of work related tasks. And there are many other tools that one could use to help with this workflow. I won't be going through all of these, and the ones that I've listed are just a few of the many that are available. Today, I'll really be talking about my teaching workflow. Let's just dive right in to a demo. So, the first file that I want to show you is the notes and admin file. From this file, I'll generate a nice-looking PDF document of notes, and I'll also keep track of some course admin. So, the file that I have here is this one, and all of the files that I'm going to show you today are taken from a course that I'm teaching at the moment this semester. What I want to do is export this entire document to LaTeX because this is where I'll be writing my course notes. But before I do that, I have some setup that I want to do, and you'll notice some of these headings are tagged as noexport, and they won't be exported. The startup setting I'll skip, and then the main thing here is the LaTeX setup. So, I'm using these #+ option lines, and I've told Org that I want to use an unusual LaTeX class, I'll have to tell Org about it later, I'll do that in a moment, and I have some LaTeX header lines, and so on. And then I have some export settings, the first export setting is to export into a different directory, not just at the same level because I want everything to go into the artifacts directory, and then I can ignore that artifacts directory using Git. This is the first source code block that we see, which is the Babel side of things, and I've called it export-setup. The way I write it is, #+begin_src, the language that I want to use, which is emacs-lisp, and maybe some options, and this is collapsed at the moment, if I expand it, you'll see inside here, this is really just Elisp, Emacs Lisp. So, the first thing I've done is, I've added this LaTeX class to the list of known LaTeX classes. And the second thing I've done is, I have locally set the value of org-latex-pdf-process, which is the compiler, to something…, this command is complicated I guess, but what the main thing it's doing is that it's moving the generated output…, sorry, the generated image files to the output directory, so that everything can remain inside of this artifacts directory, and maybe it's doing some other things. And then there are some other setup options that I'll skip. So, this is a source code block, inside of the source code block everything is basically Emacs Lisp. How do I evaluate this? I just press Control c Control c (C-c C-c), and it evaluates everything, but if I want to automate the evaluation, there's one other thing I can do. So, let me jump down to the local variables section. In this local variable section I have an eval block, so, I've added a certain hook to the org-export-before-processing-hook, and that just resolves this reference from this file. It looks for a code block titled export-setup, and it runs it right before exporting, and this is all local to this buffer. So, before I export, it'll then read the correct options. And after this setup, I have the course plan, which is just what goes into my agenda as to-dos, I'll skip that. And after that, I have the actual notes, and what they actually look like…, so, this is what they actually look like, nicely LaTeXed with diagrams and so on, everything generated from that single Org file. I'll say more about diagrams later. I also have to write assignments and assignment solutions, so let me jump to that. Again, this is a very similar file, but I want to now export different headings to different files. This is not going to be exported all at once. So, again I have some setup, some general setup that I'll skip, export setup just like before, code setup for Python, really, I have a various…, a bunch of different languages here, so Shell and Python, and some helper functions. So, let me jump to this one called togglesolutions, this is again an Emacs Lisp code block. What this does is, it tells LaTeX to either toggle the display of solutions on, or off based on what the tag is for that particular assignment. So, whether if the assignment is tagged as solved, then the solution should be displayed, otherwise they shouldn't be. And here most of the assignments are tagged as solved, so in this case if I export this, the solutions will be displayed. Let's look at that. So, I see the solutions blocks, and this is because it's calling the toggle solutions piece of code. And the properties, if I expand this properties drawer, you see this output file name has a homework one dash solved, so it has a solved suffix, and this is related to the fact that I have a solved tag up here. So, let's see what happens if I delete the solved tag, so nothing's happened yet, but if I save the file, then suddenly this homework one dash solved becomes homework one, and this is desired behavior, this is what I want because I want to keep the solved and unsolved files separate. So, once again, if I put in the solved tag, and if I save, I get back the different file name. And how did I achieve this? This is again back in the setup section, it's the process-export-filenames block. It's some big piece of Elisp that I won't go through, but basically it's mapping over Org entries, and it's either adding or removing this solved suffix based on what tag it sees. Okay, when does this code block get evaluated? Well, I want it to be evaluated right before I save because I change something, I save, and I want the properties to be get updated accordingly. If I go down to the local variables section again. Again, I have a local variables section here, and I'm evaluating this Elisp, which is setting the before-save-hook to resolve the process-export-filenames function, and so that's what gives me that functionality. And finally, I have some skeletons, which are…. Emacs has this skeleton language, which is a rudimentary templating language. So, I've defined some templates for my assignment and worksheet in this little Emacs Lisp block, which I think I usually just evaluate manually, and then if I just call it, I get a nice-looking skeleton that gives me this assignment. One thing I want to show you in these assignments, or I mean, in this file in particular, are these dot source code blocks. So, I've had to type in or draw in some graphs in this assignment, and I can do that right from Org. So, this is some piece of code that's creating a file, which has this name, and if I evaluate this block, I see a results drawer with this file. And this is a PNG file, which now gets embedded into my LaTeX document. So, this is nice, I can actually delete this from here, and when I export, the file will get attached automatically. And similarly, in some other assignments here, I have some Python source, so I've had to type in some complicated matrices, and some complicated matrix products, and so on, which I didn't want to do by hand, so that I didn't introduce errors, so I've written some Python code. If I Control c Control c (C-c C-c) on this block, you'll notice, it's in the session matrix, so it's using the previous, the same kind of session. And you'll see that the results, because of the way I chose to format them, look like a nice drawer with nicely formatted LaTeX. Once again these results I can cut from the file, and the file will get exported…, when the file gets exported, these source code blocks will get evaluated, and the answer will show up in the file. And finally, the last thing I want to show you very briefly is the web page for this course. The only thing I want to show you here is that I have a Python source code block, which pulls in my handwritten course notes, and makes them into a nice-looking list with a nice-looking order, and then just exports as HTML. So, this is what the web page looks like, and you can see it at this URL. If you go click on the 2021 link at this URL. So, that's all that I wanted to say. Thank you very much!

Back to the schedule
Previous: Using Org-mode to teach programming
Next: Managing a research workflow (bibliographies, note-taking, and arXiv)