This is a demo document about the
codename org-teaching
framework, which aims at managing teaching material using Org-mode.
Attention, this framework heavily relies on:
reveal.js.These slides are one variant of the same teaching material, also available as a PDF handbook.
You may prefer to view them in your Web browser in full-screen (F11
for instance). Should Reveal-JS fail on displaying slides, an
alternate format would be the printed PDF (but
you're gonna lose the ability to display speaker notes).
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 :
Pretty much all features of reveal.js, supported by the org-mode reveal.js exporter (org-reveal), should be supported too.
If you're already familiar with reveal.js, you may have noticed that
the current settings adopted for our slides generation are quite
frugal: no fancy 3D effects and likes.
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:
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.
The syntax in the org-mode source is:
#+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):
Tagging a section/slide with :slidesonly: means it isn't exported in the handbooks.
Below is an example (or not)…
There should be no "Only in the slides" after this section, in the
handbooks, as it has been tagged with slidesonly.
On the contrary, in the slides view, this appears, as there's a :slidesonly: tag on the current head line.
*** Only in the slides :slidesonly:
On the contrary, in the slides view, this appears,
as there's a =:slidesonly:= tag on the current head line.
Tagging a section/slide with :teachersonly: means it isn't exported in the students handbook (nor in the slides).
Below is an example…
There should be no "Only for teachers" after this section, in the slides or in the
students handbook, as it has been tagged with teachersonly.
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 (htmlize) and in the handbook (engrave-faces) :-)
<?php
class Car {
function Car() {
$this->model = "Tesla";
}
}
// create an object
$Lightning = new Car();
// show object properties
echo $Lightning->model;
?>
As you're using org-mode, its babel components are available, to embed source code in the same lesson.org source, and manage executable code and teaching material at once.
Look for literate programing instructions in the org-mode docs to know more.
Included is the use of the reveal.js jump plugin to allow jumping directly to slides # by entering a number and hitting RETURN. Quite handy while writing and testing slides.
The following SVG diagram is embedded in the HTML:
#+BEGIN_EXPORT html
<svg
width="210mm"
height="297mm">
<text
x="50"
y="50" class="fragment">A</text>
<text
x="100"
y="50" class="fragment">B</text>
<text
x="150"
y="50" class="fragment">C</text>
</svg>
#+END_EXPORT
Its elements with the fragment class can be displayed like ordinary
reveal.js fragments, as below, right here:
A better alternative is using SVG document layers, using the
reveal-svg-fragment.js plugin, as in the following section (slides only)
Example :
Please try and talk to me to suggest new stuff and/or provide patches ;)
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 section Configuration of layout).
You have 2 options to generate the different formats:
We're using the standard exporters so each output format will be exported from its corresponding umbrella .org source.
Open the corresponding org-mode source and export :
slides.org, then C-c C-e R ... for org-reveal export (to slides.html), provided that you have loaded org-reveal in Emacshandbook.org, then C-c C-e l ... for LaTeX export (to handbook.pdf)teacher-handbook.org, then C-c C-e l ... for LaTeX export (to teacher-handbook.pdf)
Depending on how you installed org-reveal (MELPA, Git submodules or otherwise), org-reveal may already be available.
If not yet, load it with M-x load-file from the location of its Git submodule (elisp/org-reveal/ox-reveal.el by default).
You may use the olberger/docker-org-export docker container image
I've prepared, to make org-mode exports. Or you may rebuild it
yourself (see below).
This is recommended to avoid man in the middle, IMHO:
cd docker
docker build -t obergixlocal/docker-org-export .
Use the provided docker/docker-org-export script, which relies on
the olberger/docker-org-export container image. See how Makefile does it.
Each lesson.org needs some configuration :
org-reveal-title-slide in slides.org.Configure in the headers elements like:
\lhead{...} and \rhead{...})\lfoot{...} and \rfoot{...})
ex: #+LaTeX_HEADER: \rhead{...} in handbook.org and
teacher-handbook.org.
I've tested DeckTape using a Docker container containing PhantomJS and
decktape to convert the slides to a single PDF document.
See the provided decktape.sh script that runs the container, bind-mounting the working dir into the container, so that input and output files can be found.
Note that I used a rebuilt Docker image, reusing the DeckTape Dockerfile, rebuilding with something alongside:
docker build -t obergixlocal/decktape .
We have experienced issues with presentations made on some versions of Firefox, which are known by reveal.js maintainer… maybe best viewed in chrome.
You may prefer to have a PDF variant of the slides (see Printing slides) in case.
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/elisp/org-revealreveal.js-jump-plugin/)So :
git submodule init
git submodule update
You may prefer to install them another way (ELPA repo, CDN, etc.)
See the org-reveal settings set in the sources and the docs for a detailed explanation.
I'm using the following for a "frugal" look close to what powerpoint or beamer (?) could look like :
#+REVEAL_HLEVEL: 1
#+REVEAL_THEME: simple
#+REVEAL_TRANS: fade
#+REVEAL_SPEED: fast
#+REVEAL_MARGIN: 0.0
#+REVEAL_EXTRA_CSS: ./presentation.css
#+REVEAL_ROOT: ./reveal.js
#+REVEAL_INIT_OPTIONS: center:false
The highest level sections include the following properties below the heading line, to customize the look of the slide.
:PROPERTIES:
:REVEAL_EXTRA_ATTR: class="center"
:reveal_background: #dbdbed
:END:
This is intended to provide some visual sense of the transitions between sections. Please adapt and report.
I'm not yet sure how much may be achieved with HTML and CSS for the title page of the slides deck, so I've relied on the embedding of a background image that will contain the logos and additional graphics.
#+REVEAL_TITLE_SLIDE_BACKGROUND: ./media/title-slide-background.png
I'm quite sure this could be improved.
org-reveal=reveal.js=I may be contacted from my Web page or via the Gitlab project.