Presentation as Code

1. Motivation

• because I was sick of Powerpoint
  
  • but also Latex was/is at some point way to much for a simple presentation
    
• ORG file should be single source of truth
  
  • you can export to multiple formats
    
    • PDF
      
    • HTML
      
    • Markdown/Asciidoc etc.
      
    • but also reveal.js presentations
      
• reveal.js looks awesome
  
  • the are lots of plugins
    
  • and lots of examples
    
• highly inspired by Reveal my Asciidoc - A deep dive into presentation-as-code
  
  • but I wanted to do it without asciidoc
    
  • “purely” in Emacs and ORG mode
    

2. Navigation

These keyboard shortcuts are available:

• ?: to see the help menu
  
• navigation:
  
  • l: next slide
    
  • h: previous slide
    
  • k: navigate up
    
  • j: navigate down
    
• m: to toggle menu
  
  • you can switch between themes
    
  • you can jump directly to slides
    
• ESC / O: slide overview
  
• CTRL+SHIFT F: search in presentation
  

3. Features

• this presentation uses CDN to fetch required (JavaScript) libraries
  
  • no need to checkout reveal.js repository
    
  • if you want to use your own theme, then you’ll need to have the CSS files somewhere on your disk
    
• you can easily embed nice looking charts and diagrams
  
  • I like c3js for charts and plantuml for diagrams
    
  • but you can add your libraries (check #REVEAL_HEAD_PREAMBLE at the beginning of the reveal.org file)
    
• diagrams are embedded as inline PNG (encoded as base64) in the resulting HTML document
  
  • I use a hook to transform each PNG into base64 on export
    
  • This hook is part of the project variables defined in .dir-locals.el
    
• I distinguish between content and generated HTML/CSS content (available at public)
  

4. Where to start?

For the beginning I’d recommend you the following steps:

• you decide which one to use: org-reveal or org-re-reveal
  
  • I personally prefer org-re-reveal
    
• have a look at this repository
  
• feel free to use my reveal.org template
  
• I use project specific variables defined in .dir-locals.el
  
  • content of revealjs-plugins-conf.js is assigned to org-re-reveal-init-script
    
  • use a hook to convert every PNG file into base64 data and insert it directly into the HTML document
    

5. What if you don’t use ORG and Emacs?

• Don’t worry!
  
• You can still use plain HTML to create your reveal.js presentation (not really recommended)
  
• You could use markdown
  
• Have a look at asciidoctor (asciidoc syntax) and asciidoctor reveal.js
  
  • asciidoc syntax is really simple
    
  • you have great support for charts, source code listings and many other things
    
  • also checkout Zenika’s adoc presentation model repository for a full-featured example
    
• you can also export from ORG to asciidoctor using org-asciidoc
  
  • recently I’ve submitted an issue for better literals support
    

6. Showcase

Now it’s time for some demos

• Charts using C3.js
  
• Diagrams using PlantUML
  
• Literate programming
  

7. C3.js

Awesome D3.js based chart library. Basic usage in the ORG file:

#+begin_export html
<div id="chart_example"></div>
var chart = c3.generate({
    bindto: '#chart_example',
    size: {
      width: <svg width>,
      height: <svg height>,
    },
    data: {
     <Your data>
    }
});
<script>
#+end_export

All charts are interactive. So make sure you use your mouse! And have a look at all examples.

7.1. Basic line chart

#+begin_export html
<div id="chart"></div>
<script>
var chart = c3.generate({
    bindto: '#chart',
    size: {
      width: 800,
      height: 550,
    },
    data: {
      columns: [
        ['data1', 30, 200, 100, 400, 150, 250],
        ['data2', 50, 20, 10, 40, 15, 25]
      ]
    }
});
</script>
#+end_export

7.2. Pie chart

#+begin_export html
<div id="chart2"></div>
<script>
var chart = c3.generate({
    bindto: '#chart2',
    size: {
      width: 600,
      height: 550,
    },
    data: {
        columns: [
            ['data1', 30],
            ['data2', 120],
            ["setosa", 0.2, 0.2, 0.2, 0.2, 0.2, 0.4, 0.3, 0.2, 0.2, 0.1, 0.2, 0.2, 0.1, 0.1, 0.2, 0.4, 0.4, 0.3, 0.3, 0.3, 0.2, 0.4, 0.2, 0.5, 0.2, 0.2, 0.4, 0.2, 0.2, 0.2, 0.2, 0.4, 0.1, 0.2, 0.2, 0.2, 0.2, 0.1, 0.2, 0.2, 0.3, 0.3, 0.2, 0.6, 0.4, 0.3, 0.2, 0.2, 0.2, 0.2],
            ["versicolor", 1.4, 1.5, 1.5, 1.3, 1.5, 1.3, 1.6, 1.0, 1.3, 1.4, 1.0, 1.5, 1.0, 1.4, 1.3, 1.4, 1.5, 1.0, 1.5, 1.1, 1.8, 1.3, 1.5, 1.2, 1.3, 1.4, 1.4, 1.7, 1.5, 1.0, 1.1, 1.0, 1.2, 1.6, 1.5, 1.6, 1.5, 1.3, 1.3, 1.3, 1.2, 1.4, 1.2, 1.0, 1.3, 1.2, 1.3, 1.3, 1.1, 1.3],
            ["virginica", 2.5, 1.9, 2.1, 1.8, 2.2, 2.1, 1.7, 1.8, 1.8, 2.5, 2.0, 1.9, 2.1, 2.0, 2.4, 2.3, 1.8, 2.2, 2.3, 1.5, 2.3, 2.0, 2.0, 1.8, 2.1, 1.8, 1.8, 1.8, 2.1, 1.6, 1.9, 2.0, 2.2, 1.5, 1.4, 2.3, 2.4, 1.8, 1.8, 2.1, 2.4, 2.3, 1.9, 2.3, 2.5, 2.3, 1.9, 2.0, 2.3, 1.8],
        ],
        type : 'donut',
        onclick: function (d, i) { console.log("onclick", d, i); },
        onmouseover: function (d, i) { console.log("onmouseover", d, i); },
        onmouseout: function (d, i) { console.log("onmouseout", d, i); }
    },
    donut: {
        title: "Iris Petal Width"
    }
});
</script>
#+end_export

7.3. Combination of line and bar chart

#+begin_export html
<div id="chart3"></div>
<script>
var chart = c3.generate({
    bindto: '#chart3',
    data: {
        columns: [
            ['data1', 30, 20, 50, 40, 60, 50],
            ['data2', 200, 130, 90, 240, 130, 220],
            ['data3', 300, 200, 160, 400, 250, 250],
            ['data4', 200, 130, 90, 240, 130, 220],
            ['data5', 130, 120, 150, 140, 160, 150],
            ['data6', 90, 70, 20, 50, 60, 120],
        ],
        type: 'bar',
        types: {
            data3: 'spline',
            data4: 'line',
            data6: 'area',
        },
        groups: [
            ['data1','data2']
        ]
    },
    size: {
      width: 800,
      height: 550,
    }
});
</script>
#+end_export

7.4. Custom data colors

#+begin_export html
<div id="chart4"></div>
<script>
var chart = c3.generate({
    bindto: '#chart4',
    size: {
      width: 700,
      height: 550,
    },
    data: {
        columns: [
            ['data1', 30, 20, 50, 40, 60, 50],
            ['data2', 200, 130, 90, 240, 130, 220],
            ['data3', 300, 200, 160, 400, 250, 250]
        ],
        type: 'bar',
        colors: {
            data1: '#ff0000',
            data2: '#00ff00',
            data3: '#0000ff'
        },
        color: function (color, d) {
            // d will be 'id' when called for legends
            return d.id && d.id === 'data3' ? d3.rgb(color).darker(d.value / 150) : color;
        }
    }
});
</script>
#+end_export

8. Diagrams

I like to express myself through pictures/diagrams. A picture is still worth a thounsand words. That’s why I use them:

• to visualize
  
  • software architecture
    
  • (cloud) infrastructure
    
  • depedencies between some components
    
  • mind maps
    
• to document
  
  • architectural decisions
    
  • overall project state
    

8.1. Plantuml

Let me quote Wikipedia:

PlantUML is an open-source tool allowing users to create diagrams from a plain text language. Besides various UML diagrams, PlantUML has support for various other software development related formats (such as Archimate, Block diagram, BPMN, C4, Computer network diagram, ERD, Gantt chart, Mind map, and WBD), as well as visualisation of JSON and YAML files.

The language of PlantUML is an example of a domain-specific language. Besides its own DSL, PlantUML also understands AsciiMath, Creole, DOT, and LaTeX. It uses Graphviz software to layout its diagrams and Tikz for LaTeX support. Images can be output as PNG, SVG, LaTeX and even ASCII art. PlantUML has also been used to allow blind people to design and read UML diagrams.

Just give it a try. You won’t regret it! Also check out real-worl-plantuml.com for some real examples.

Basic usage in ORG:

#+begin_src plantuml :noweb-ref <id> <options>
@startuml
...
@enduml
#+end_src

9. Literate programming

• You can use ORG babel to execute code within ORG documents.
  
• similar to IPython/Jupyter notebooks
  
• you can use Babel to document your code and the results/output at the same place.
  

9.1. Shell

uname

Linux

9.2. HTTP requests

GET https://api.github.com/repos/zweifisch/ob-http/languages
Accept: application/vnd.github.moondragon+json

{
  "Emacs Lisp": 15327,
  "Shell": 139
}

ob-http is awesome!

9.3. Elisp

(directory-files ".")

("." ".." "2022-hexagonal-architecture.org" "2022-presentations-as-code.org" "2023-kubernetes.org" "images" "index.org" "notes-style.setup" "reveal.org" "revealjs-plugins-conf.js" "themes")

9.4. Golang

package main
import "fmt"

func main() {
    queue := make(chan string, 2)
    queue <- "one"
    queue <- "two"
    close(queue)

    for elem := range queue {
        fmt.Println(elem)
    }
}

one
two

9.5. Python

num = 8
num_sqrt = num ** 0.5
print('The square root of %0.3f is %0.3f'%(num ,num_sqrt))

The square root of 8.000 is 2.828

9.6. gnuplot

set title "Students' Grades"
set yrange[0:10]
set style data histogram
set terminal png size 400,300
plot data using 2:xtic(1) title 'Maths', '' using ($3) title 'Physics'

• Source
  

10. Conclusion

• ORG mode is still one of the most powerful markup languages for text
  
• if you don’t have the time (and motivation) to learn Emacs/ORG mode
  
  • have a look at asciidoctor and asciidoc
    
  • if you don’t like ruby and gems, check out AsciidoctorJ which is a library for running asciidoctor on the JVM
    
  • there are tons of extensions you can chose from
    
• creating beautiful presentations for reveal.js is fun and doable just by writing (markup) code
  
• convince yourself and have a look at the source of this presentation
  
  • text content and images at the same place
    
  • charts can be easily embedded via custom HTML code
    
  • all sorts of diagrams can be generated using PlantUML
    
  • you can focus on writing content rather than fixing your presentation’s layout
    
• you can do way more with ORG
  
  • ORG tutorials is full of interesting ideas
    

11. Contact

About

dornea.nu

Blog

blog.dornea.nu

Github

github.com/dorneanu

Twitter

@victordorneanu

LinkedIn

linkedin.com/in/victor-dorneanu

Threema

HCPNAFRD