“There are always three speeches, for every one you actually gave. The one you practiced, the one you gave, and the one you wish you gave.”
Dale Carnegie
Sometimes even developers want to present something. It’s nice when there’s a tool that picks up the developers in their comfort zone. Software developers are a special clientele and have very specific requirements for a software solution for creating and giving presentations. If you research the requirements in the web, you will find the following list.
Compatibility with different operating systems: The software should run smoothly on different operating systems such as Windows, macOS and Linux to ensure broader compatibility and deployment options.
Support for program code: Embedding and neat formatting of program code in slides, including syntax highlighting to illustrate and present code examples in a readable way.
Version control integration: Ability to integrate with version control systems such as Git so that presentations are versioned and changes are traceable.
Extensibility and customizability: Options for extensions and plugins to extend functionality or API access to customize the software to specific workflows.
Collaboration features: Options for easy collaboration and joint editing of presentations, ideally in real time to facilitate teamwork.
Export options: Multiple export options to different formats such as PDF, HTML, video or as an executable file to be able to share the presentation on different platforms.
Interactivity feature: Possibility to add interactive elements such as polls, tests or embedded demos to make the presentation more dynamic.
Ease of use: An intuitive user interface that enables presentations to be created quickly and effectively even without extensive training.
The last point can be discussed endlessly in developer circles and since this article does not offer a solution with an intuitive user interface, we will deliberately ignore it. Four popular solutions among developers are:
reveal.js: A web-based presentation software that supports Markdown and allows programmers to write their slides directly in HTML. It offers many possibilities for interactivity.
Jupyter Notebooks: Originally developed for scientific presentations, they are ideal for technical demos as they support live code, equations and visualizations.
impress.js: Similar to reveal.js, impress.js is an advanced presentation toolkit based on web technologies that provides developers with a highly customizable platform for creating presentations.
LaTeX Beamer: For developers who are familiar with \LaTeX, the \text{\small{BEAMER}} class offers a way to write presentations with LaTeX, which is especially useful for academic presentations with a lot of technical or mathematical content.
This article is about an Asciidoctor extension that creates a reveal.js presentation. Asciidoctor is a fast, open text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook, PDF and other formats. Developed in Ruby, Asciidoctor offers a modern and clean alternative to other markup languages such as Markdown for writing documents, books, websites, presentations and technical texts.
Asciidoctor and reveal.js allow you to create presentations from AsciiDoc files by converting AsciiDoc to HTML for reveal.js. This combines the simplicity of AsciiDoc with the dynamic presentation features of reveal.js to create professional materials.
A simple presentation in AsciiDoc starts with a title area containing the title, author and a list of document settings. So many are usually not necessary, but for demonstration purposes a little exaggeration was used here.
= Ancestor API :author: Jens Kaiser :source-highlighter: highlight.js :highlightjs-languages: asciidoc :revealjs_hash: true :revealjs_theme: moon :revealjs_fragmentInURL: true :revealjs_autoPlayMedia: true :title-slide-background-video: families.mp4 :title-slide-background-video-loop: true :title-slide-background-video-muted: true :favicon: images/favicon.svg
AsciiDoctor automatically creates a first slide from the title section. All further slides are created from level two and three chapters. This replicates the horizontal and vertical slides of reveal.js. Horizontal slides are the main slides and vertical slides are used to deepen the content of the main slides.
The following fragment shows a slide with various dynamic features.
[transition=zoom,,background-video="pexels-german-korb-5643530 (1440p).mp4, options="loop,muted"] == HATEOAS Links [%step,none] * **self** the self-link of the ancestor resource * **father** the optional link to the father resource * **mother** the optional link to the mother resource * **child** the optional link to a child resource * **family** the link to the family resource [.notes] -- Da es meist mehrere Kinder gibt heißt der child Link children --
Above the heading == HATEOAS Links there are some optional adjustments for the slide. In this case, the fade-in takes place via the transition=zoom and a video runs in a continuous loop in the background. The heading is followed by a list, which is displayed line by line using the %step option. At the end of the slide there is a .notes block. This block does not appear on the slide but serves as a memory aid for the presenter.
The resulting slide is shown below. The font size and colors come from the reveal.js theme moon, which was specified in the title section. The second line doesn’t seem to be legible here, but remember, it’s a video.
When presenting the slide, the presenter is supported by reveal.js with a special second window. This shows the current content, the upcoming content, the notes and a time overview.
An important feature for software developers is the display of source code in their presentation. AsciiDoctor’s source blocks provide them with the best possible support here.
=== Link Examples
[source,json,indent=0]
----
include::{test_source}/JohannChristophKaiser.json[lines=12..24]
----
This slide contains a JSON code from an included file JohannChristophKaiser.json. The entire file was not included, but only lines 12 to 24. The unnecessary spaces at the beginning of the line were truncated using the “indent=0” option.
The result displays the formatted JSON code using the highlight.js library. In this example, it does not look particularly exciting, but this is only due to the rather boring JSON format.
To automate the creation of the presentation, it can be integrated directly into a Maven build process. All you have to do is configure the revealjs backend in the asciidoctor-maven-plugin. The configuration for a genealogy presentation is shown here.
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>2.2.4</version>
<executions>
<execution>
<id>asciidoc-to-html</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
</execution>
</executions>
<configuration>
<backend>revealjs</backend>
<sourceDocumentName>anchestors.adoc</sourceDocumentName>
<requires>
<require>asciidoctor-revealjs</require>
</requires>
<attributes>
<revealjsdir>https://cdn.jsdelivr.net/npm/reveal.js</revealjsdir>
</attributes>
</configuration>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>2.5.10</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-revealjs</artifactId>
<version>5.1.0</version>
</dependency>
</dependencies>
</plugin>
If the plugin is executed, an ancestors.html file is generated from the ancestors.adoc input. This can be displayed directly with a web browser and requires no further infrastructure.