How to create presentations with emacs-reveal

(Press ? for help, n and p for next and previous slide)

Jens Lechtenbörger (License Information)
July 2018

Presentation Hints

General

This is a reveal.js presentation
Key bindings and navigation
- Press “?” to see key bindings of reveal.js
  - In general, “n” and “p” move to next and previous slide; mouse wheel works as well
  - Search with Ctrl-Shift-F
- Up/down (swiping, arrows) move within sections, left/right jump between sections (type “o” to see what is where)
- Type slide’s number followed by Enter to jump to that slide
- Browser history (buttons, Alt-CursorLeft, Alt-CursorRight)
- Zoom with Ctrl-Mouse or Alt-Mouse

Offline work

Students often ask for download-able presentations
Alternatives
1. Clone repository, build presentations locally (see Usage)
2. Download build artifacts from recent pipeline (if not expired)
3. Generate PDF
  - Why, really?
    - Why not download source files instead?
    - Org mode, which is plain text
  - Change the URL by adding “?print-pdf” after “.html”, then print to PDF file (usually, Ctrl-p)
  - Alternatively, generate PDF via LaTeX from org source file

Audio

If audio is embedded, the free Ogg format is used
- Playback should start automatically
  - Currently, you should be hearing Enthusiast by Tours
    - Licensed under a Creative Commons Attribution License
  - See compatibility and known issues of the underlying audio plugin
  - Firefox, which I recommend as browser in general (here in English and here in German), seems to work everywhere
- Audio controls are shown at bottom left

(Speaker) Notes

Slides contain additional notes as plain text if you see the folder icon at the top right (as on this slide)
- Click on that icon or press “s” to see the “speaker notes view”
- You need to allow pop-ups
  - If the pop-up window does not work, you may need to press “s” twice or close the pop-up window once

Introduction

What’s This?

Emacs-reveal is free software to generate reveal.js presentations (slides with audio) from simple text files in Org mode
“ Image ” under CC0; converted from Pixabay
- Benefits
- For your audience
  - Self-contained presentations embedding audio
  - Usable on lots of (including mobile and offline) devices with just a browser
- For you as producer
  - Separation of layout and contents
    - Similarly to, e.g., LaTeX
  - Simple text format allows diff and merge for ease of collaboration

Prerequisites

I suppose (and strongly recommend) that you use GNU/Linux (help on getting started)
- Actually, not much here is operating system specific
Emacs-reveal should really be used with the text editor GNU Emacs
- (You could try other editors and build presentations within GitLab, thanks to emacs-reveal’s GitLab infrastructure)
  - (In fact, you do not need an editor at all but could edit presentations using a Web browser on GitLab.com, e.g., with the Web IDE (requires login))

Installation

Download software
- Install emacs-reveal-howto
  - git clone https://gitlab.com/oer/emacs-reveal-howto.git
  - cd emacs-reveal-howto/
- Install submodules
  - git submodule sync --recursive
  - git submodule update --init --recursive
Install and configure Emacs packages
- emacs --batch --load emacs-reveal/install.el --funcall install
- Add a line like this to ~/.emacs
  - (load "/path/to/emacs-reveal/reveal-config.el")

Usage

Alternatives

Create presentations locally on Command Line
Create presentations in Emacs
Create and publish presentations on GitLab
“ GitLab Logo ” by GitLab under CC BY-NC-SA 4.0; from gitlab.com
- Based on underlying continuous integration infrastructure using Docker image
  “ Docker logo ” under Docker Brand Guidelines; from Docker

Build Presentations on Command Line

Create Org file in directory emacs-reveal-howto/
- See contained source file for this presentation, howto.org
Build presentations for files ending in .org (except internal ones listed in elisp/publish.el)
- emacs --batch --load elisp/publish.el --funcall org-publish-all
- Presentations are built in subdirectory public/
Open presentation in Firefox
- E.g.: firefox public/howto.html
Optional: Copy public/ to web server for public accessibility

Building Presentations in Emacs

Generate HTML presentation for visited .org file using the usual Org export functionality:
Press C-c C-e R B
- This generates an HTML file in the same directory and opens it in your default browser
- For this to work, necessary resources, in particular the reveal.js directory, must be accessible in the .org file’s directory

Build Presentations on GitLab

Fork project on GitLab (fork documentation)
- (Instead of forking, maybe use git clone as shown above; import that as new project on GitLab)
Create project’s files locally
- git clone <the URL of YOUR GitLab project>
Create or update Org files in cloned directory, add, commit, and push (see next slide)
GitLab infrastructure picks up changes and publishes presentations as GitLab Pages
- Takes some minutes
- Go to Settings → Pages to see the Pages’ address

On Git

Install Git (getting started)
- The Pro Git book is a great source in general
Short in-browser Git demo
- Explains Git commands add, commit, push, and more
Slightly longer Git introduction as OER (created with emacs-reveal)

Some Presentation Features

Text Slide

A list
With a sub-list whose items appear
- This is emphasized
- This is bold
- This looks like code
- This is green
- Nothing special

Some Fragment Styles

Forget
Shrink
Grow
Very important

Fragments with Custom Order

I’m first.
Fourth.
Third
Second
I’m also first.

Centered Text

Just some horizontally centered text. Created by assigning a class with text-align: center.

On Sections

This slide is part of section Some Presentation Features
- We can link to slides, e.g., the previous slide
  - You can use the browser history to go back
- Side note: Check source code to see two variants of link targets used on this slide

This slide can also be perceived as its own subsection
- The next slide is on a deeper level of nesting
(This list item appears simultaneously with previous bullet point)

Another Slide

This slide is on a deeper level of nesting
This level of nesting is not shown in the table of contents in the slide’s bottom
By the way, the headings in the table of contents below are hyperlinks
- And your browser remembers the history, back/forward buttons and shortcuts should work
- Mousewheel and swiping work

Two Columns: Pro/Con of emacs-reveal

Pro

Free/libre open source software
Device-independent presentations
- Also mobile and offline
- Generated from simple text format
  - Easy to learn
  - Collaboration with diff/merge/git
  - Separation of layout and content

Con

No WYSIWYG
(Need to learn something new)

Figures and Audio

Slide with Figure and Audio

This figure is part of a different presentation
“ Visualization of Clock algorithm for page replacement ” by Jens Lechtenbörger under CC BY-SA 4.0; from GitLab
The song Enthusiast by Tours is licensed under a Creative Commons Attribution License

Figure with Caption and License

Display image with meta-data specified in file
- Simplify sharing of images with source and license
Functionality and meta-data format are specific to emacs-reveal
- See next slide for sample file

Balance tipping in favor of Yes

To share or not to share

“ Image ” under CC0; converted from Pixabay

Meta-Data File for Previous Image

;; Semicolon starts comment until end of line (Emacs Lisp).
;; Note that the line for dc:title below is just a comment.  In that
;; case, "Image" is used as generic title; uncomment for real title.
;; CC0 does not require attribution of author/creator; uncomment if needed.

((filename . "./figures/3d-man/decision-1013751_1920.jpg") ; Note the path prefix
; (dc:title . "The title given by the author")
 (licenseurl . "https://creativecommons.org/publicdomain/zero/1.0/")
 (licensetext . "CC0")
; (cc:attributionName . "Jens Lechtenbörger")
; (cc:attributionURL . "https://gitlab.com/lechten")
 (dc:source . "https://pixabay.com/en/decision-question-response-1013751/")
 (sourcetext . "Pixabay")
 (imgalt . "Balance tipping in favor of Yes")
 (imgadapted . "converted from") ; Adjust as needed
 (texwidth . 0.5) ; Width in percent of textwidth for LaTeX export
)

An Image Grid: Computers

Server

“ Server ” under CC0; from Pixabay

C64

“ C64 ” under CC0; from Pixabay

Notebook

“ Notebook ” under CC0; from Pixabay

Router

“ Router ” under CC0; from Pixabay

Car

“ Car ” under CC0; from Pixabay

Doll

“ Doll ” under CC0; from Pixabay

“ TV ” under CC0; from Pixabay

Smart watch

“ Smart watch ” under CC0; cropped from Pixabay

Fairphone 2

“ Fairphone 2 ” by Kaihsu Tai under CC BY-SA 4.0; cropped from Wikimedia

Creation of Previous Image Grid

Single line in source file, using macro revealgrid

{{{revealgrid(42,"./figures/devices/computer.grid",60,4,3,"\"ga1 ga2 ga2 ga3\" \"ga1 ga4 ga5 ga6\" \"ga7 ga8 ga9 ga9\"")}}}

Arguments explained in emacs-reveal/config.org

With computer.grid as follows

("./figures/devices/white-male-1834091_1920.meta"
 "./figures/devices/commodore-160186_1280-CC0.meta"
 "./figures/devices/laptop-154091_1280.meta"
 "./figures/devices/router-157597_1280.meta"
 "./figures/devices/car-49278_960_720.meta"
 "./figures/devices/beauty-1260974_1920.meta"
 "./figures/devices/vintage-tv-1116587_960_720.meta"
 "./figures/devices/smartwatch-1874536_1280.meta"
 "./figures/devices/Fairphone_2_reverse.meta")

Appearing Items with Audio

(Audios produced with MaryTTS, converted to Ogg format with Audacity)

One
Two
Three

Quizzes

Quiz Plugin

Emacs-reveal embeds this quiz plugin
- Demo of plugin’s author
In presentations, quizzes support active learning
- In particular, retrieval practice

Sample Quiz

The End

Go for it!

Person taking steps to top

The road ahead …