How to teach using org-mode for fun and profit

This framework heavily relies on org-mode (version 9 at the time of writing) and the org-reveal exporter for reveal.js.

The goal is to be able to edit a single file (namely lesson.org) which will contain, in a single source, all the content of a lesson, written with org-mode syntax.

From this single source, several documents are generated :

• slides (as a dynamic Web document) for overhead presentation
• a handbook that contains the same information (or more) and can be handed to the students for work outside the classroom (a PDF file)
• another handbook for the teaching team, to provide additional instructions (also a PDF file)

Pretty much all features of reveal.js supported by the org-mode reveal.js exporter org-reveal, should be supported too.

An example org-reveal document is available here for inspiration (it's the export of org-reveal's README.org, actually).

I'm using the 3 levels of outlining / sectioning so that the content can be sectioned in the same way in lesson.org and appear appropriately in the slides and handbook, with these principles:

1. First level outlines define main sections of the document.
2. Second level outlines are the main "horizontal" slides that will be played with page up/down
3. Third level outlines may be used for additional content ("vertical" slides) that may be skipped for the presentation, but is still accessible with cursor keys.

org-reveal's Speaker notes may be added to the slides (and will only appear on dual-screen presentation after having pressed 's': standard reveal.js feature).

They will be masked for the audience, but will, by default appear in the handbook given to the students.

#+BEGIN_NOTES
This is a note
#+END_NOTES

I've implemented some easy ways to preserve some of the content of the same lesson.org source for certain outputs (using org exporter's standard EXCLUDE_TAGS):

Slides only material

that won't be embedded in the handbook : surprise stuff for live audience, or HTML-only hacks;

Teachers only material

secret knowledge that only adults need to know (for instance), which won't be exported;

Handbook only material

stuff that only fits in the handbook, and/or only exports as LaTeX and not HTML.

Tagging a section/slide with :slidesonly: means it isn't exported in the handbooks.

Below is an example (or not)…

Tagging a section/slide with :teachersonly: means it isn't exported in the students handbook (nor in the slides).

Below is an example…

This slide/section contains notes, but only part of it is displayed in the presentation notes included in the handbook. Special notes and are kept only for the teachers handbook.

We use an org-mode drawer for that (additional benefit is that the content is folded by default in emacs, as it may be verbose and/or "sensitive") :

#+BEGIN_NOTES
This part of the note can be viewed by the students in the handbook.

:TEACHERSONLY:
Not this one
:END:
#+END_NOTES

Just like sections are for slides only, others can be for the handbook only, using the handbookonly tag. This may be useful for Annex sections for instance, or for stuff that the HTML exporter won't like, with inline LaTeX.

Code is colorized / highlighted in the slides :-)

Please try and talk to me to suggest new stuff and/or provide patches ;)

There's no production chain, makefiles or other authoring tools.

No new Elisp either.

Only one file should be edited for writing the lesson's material : lesson.org

Only exception is modification of some configurations for title pages and other bits that shouldn't change much in time (see next section).

Each lesson.org needs some configuration :

• Configure org-reveal-title-slide in slides.org.
• Configure header (\lhead{...} and \rhead{...}) and footer (\lfoot{...} and \rfoot{...}) elements in the headers like #+LaTeX_HEADER: \rhead{...} in handbook.org and teacher-handbook.org.

We're using the standard exporters so each output format will be exported from its corresponding umbrella .org source :

slides

open slides.org, then C-c C-e R ... for org-reveal export (to slides.html), provided that you have loaded org-reveal in Emacs

handbook

open handbook.org, then C-c C-e l ... for LaTeX export (to handbook.pdf)

teacher handbook

open teacher-handbook.org, then C-c C-e l ... for LaTeX export (to teacher-handbook.pdf)

See the contents of the files… but be wary that it's sometimes messy and incrementally obtained.

Emacs is your buddy.

Git clone from https://gitlab.com/olberger/org-teaching.git (see the Gitlab project)

The repository contains Git submodules for :

• reveal.js
• org-reveal

So :

git submodule init
git submodule update

You may prefer to install them another way (ELPA repo, CDN, etc.)

• All contributors to org-mode (special kudos to Carsten Dominik and Bastien Guerry)
• Yujie Wen for org-reveal
• Hakim El Hattab for reveal.js
• My colleagues at Telecom SudParis who had to teach with this tool without much rehersal
• Our students who endured it for a brand new course (and included bugs)

I may be contacted from my Web page or via the Gitlab project.