It seems that I have made dozens of presentations for colleagues, customers and public speaking during my career in IT. For many years, Powerpoint has been a natural and reliable choice for me as a slide-making tool. But this year the situation has qualitatively changed. From February to May, I had the opportunity to speak at five conferences, and the slides for the reports had to be prepared in a short time, but with high quality. The question arose about delegating that part of the work regarding the visual design of the slides to other people. Once I tried to work with a designer by sending .pptx files by mail, but the work turned into chaos: no one knew which version of the slides was βthe newestβ, and the layout was βdrivingβ due to differences in the versions of Powerpoint and fonts on our machines . And I decided to try something new. I tried it, and since then I do not think to return to Powerpoint.
What do we want
About a year and a half ago, we at the company abandoned the use of Word for creating design documents, having encountered the same problems: although Word is good for typing a small document, as volumes grow, it becomes difficult to collaborate and achieve high-quality and unified design. Our choice fell on , and we do not cease to rejoice at this choice, but this is a topic for a separate article. Around the same time, we learned the effectiveness of one of the βeverything as codeβ DevOps principles, so the choice of requirements for a new technology for creating presentation slides was pretty obvious:
- The presentation must be a plain text file in a markup language.
- Our slides are about development projects, so the markup should allow you to easily, without resorting to external systems, insert
- code snippets with syntax highlighting,
- simple diagrams in the form of geometric shapes connected by arrows,
- UML diagrams, flowcharts and more.
- The presentation project must be kept in version control.
- Validation and assembly of finished slides should be done in a CI system.
Today, there are two basic options for creating slides in markup languages: for LaTeX or one of the frameworks for creating slides in HTML/CSS (, , and many others).
Although my soul lies with LaTeX, my mind told me that the choice of a solution that I would not use alone should be on the side of a solution that is familiar to a wider circle of people. Not everyone knows LaTeX, and if your daily practice is not related to writing scientific articles, then you are unlikely to have time to dive into the vast intricate world of this system.
However, the knowledge of HTML / CSS is not a ubiquitous skill: for example, I do not fully own it. Fortunately, this is where AsciiDoctor, already familiar to us, comes to the rescue: converter allows you to create RevealJS slides using AsciiDoctor markup. And it's easy to learn and accessible to everyone!
How to encode slides
To understand the essence of AsciiDoctor slide coding, it is easiest to give specific examples. All of them are from actual slides I made for my conference talks this year.
A slide with a title and a list in paragraphs that open one after the other:
== ΠΠ°ΡΠ΅ΠΌ Π½Π°ΠΌ Streams API?
[%step]
* Real-time stream processing
* Stream-like API (map / reduce)
* ΠΠΎΠ΄ ΠΊΠ°ΠΏΠΎΡΠΎΠΌ:
** ΠΠ²ΡΠΎΠΌΠ°ΡΠΈΡΠ΅ΡΠΊΠΈΠΉ offset commit
** Π Π΅Π±Π°Π»Π°Π½ΡΠΈΡΠΎΠ²ΠΊΠ°
** ΠΠ½ΡΡΡΠ΅Π½Π½Π΅Π΅ ΡΠΎΡΡΠΎΡΠ½ΠΈΠ΅ ΠΎΠ±ΡΠ°Π±ΠΎΡΡΠΈΠΊΠΎΠ²
** ΠΠ΅Π³ΠΊΠΎΠ΅ ΠΌΠ°ΡΡΡΠ°Π±ΠΈΡΠΎΠ²Π°Π½ΠΈΠ΅Experience the Power of Effective Results
Header and source code snippet with syntax highlighting:
== Kafka Streams API: ΠΎΠ±ΡΠ°Ρ ΡΡΡΡΠΊΡΡΡΠ° KStreams-ΠΏΡΠΈΠ»ΠΎΠΆΠ΅Π½ΠΈΡ
[source,java]
----
StreamsConfig config = ...;
//ΠΠ΄Π΅ΡΡ ΡΡΡΠ°Π½Π°Π²Π»ΠΈΠ²Π°Π΅ΠΌ Π²ΡΡΠΊΠΈΠ΅ ΠΎΠΏΡΠΈΠΈ
Topology topology = new StreamsBuilder()
//ΠΠ΄Π΅ΡΡ ΡΡΡΠΎΠΈΠΌ ΡΠΎΠΏΠΎΠ»ΠΎΠ³ΠΈΡ
....build();
----Experience the Power of Effective Results
During the preparation of the report, the code demos are repeatedly reworked and improved, so the ability to quickly copy and paste the "raw code" directly into the slide, ensuring the relevance of the demo and not worrying about syntax highlighting, is invaluable.
Title, illustration and text (we perform the layout on the slide in cells ):
== Kafka Streams in Action
[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
βKafka Streams in Actionβ, November 2018
* ΠΡΠΈΠΌΠ΅ΡΡ ΠΊΠΎΠ΄Π° Π΄Π»Ρ Kafka 1.0
|===Experience the Power of Effective Results
Sometimes you donβt need a title, but just a full-screen image is needed to illustrate your idea:
[%notitle]
== ΠΠΈΡΡ Π² Π»Π΅Π³Π°ΡΠΈ Π½Π΅Π»Π΅Π³ΠΊΠΎ
image::swampman.jpg[canvas, size=cover]Experience the Power of Effective Results
Often a thought needs to be supported by a simple diagram, in the form of "squares connected by arrows." Fortunately, AsciiDoctor is integrated with the system - a language that allows you to describe graph diagrams based on the description of the vertices and the connections between them. Graphviz needs to be mastered, but based on the available examples, it's pretty easy to do! Here's what it looks like:
== ΠΠΈΡΠ΅ΠΌ βBet Totalling Appβ
ΠΠ°ΠΊΠΎΠ²Π° ΡΡΠΌΠΌΠ° Π²ΡΠΏΠ»Π°Ρ ΠΏΠΎ ΡΠ΄Π΅Π»Π°Π½Π½ΡΠΌ ΡΡΠ°Π²ΠΊΠ°ΠΌ, Π΅ΡΠ»ΠΈ ΡΡΠ³ΡΠ°Π΅Ρ ΠΈΡΡ
ΠΎΠ΄?
[graphviz, "counting-topology.png"]
-----
digraph G {
graph [ dpi = 150 ];
rankdir="LR";
node [fontsize=18; shape="circle"; fixedsize="true"; width="1.1"];
Store [shape="cylinder"; label="Local Store"; fixedsize="true"; width="1.5"]
Source -> MapVal -> Sum -> Sink
Sum -> Store [dir=both; label=" n "]
{rank = same; Store; Sum;}
}
-----Experience the Power of Effective Results
In the case when you need to edit the caption on the figure, change the direction of the arrow, etc. - this can be done directly in the presentation code, instead of redrawing the picture somewhere and re-inserting it into the slide. This greatly increases the speed of work on slides.
More complicated example:
== ΠΠ΅Π²ΠΎΡΠΏΡΠΎΠΈΠ·Π²ΠΎΠ΄ΠΈΠΌΠ°Ρ ΡΠ±ΠΎΡΠΊΠ°
[graphviz, "unstable-update.png"]
-----
digraph G {
rankdir="LR";
graph [ dpi = 150 ];
u -> r0;
u[shape=plaintext; label="linter updaten+ 13 warnings"]
r0[shape=point, width = 0]
r1 -> r0[ arrowhead = none, label="master branch" ];
r0-> r2 []; b1 -> b4; r1->b1
r1[label="150nwarnings"]
b1[label="Β± 0nwarnings"]
b4[label="Β± 0nwarnings"]
b4->r2
r2[label="163nwarnings", color="red", xlabel=<<font color="red">merge blocked</font>>]
{rank = same; u; r0; b4;}
}
-----Experience the Power of Effective Results
By the way, experimenting with Graphviz and debugging pictures is convenient on the page .
Finally, if you need to insert a flowchart, class diagram or other standardized diagram into a slide, then another system integrated with AsciiDoctor can come to the rescue, . My colleague Nikolai Potashnikov wrote about the extensive possibilities of PlantUML .
Turning a presentation project into code stored on a version control system makes it possible to organize joint work on a presentation, first of all, to separate the tasks of creating content and design. The design of slides (fonts, backgrounds, padding) in RevealJS is described using CSS. My personal skill with CSS best conveys - but it's not scary when there are people who work with CSS much more dexterously and faster than me. The bottom line is that with a presentation deadline fast approaching, we can work on multiple files at the same time via Git and develop a collaborative speed that's not possible with emailed .pptx files.
Building an HTML page with slides
Plain text sources are great, but how do you compile them into the presentation itself?
AsciiDoctor is a project written in Ruby and there are several ways to start it. First, you can install the Ruby language and run asciidoctor directly, which is probably the closest Ruby developer can get.
If you don't want to mess with your Ruby installation, you can use the docker image , into which, when launched, you can connect the folder with the project sources via VOLUME and get the result in the specified location.
The option I chose may seem somewhat unexpected, but it is the most convenient for me as a Java developer. It does not require Ruby or docker to be installed, but allows you to generate slides using a Maven script.
The point is that the project - The Java implementation of the Ruby language is so good that it allows you to run almost everything created for Ruby in a Java machine, and running AsciiDoctor is one of the most common uses of JRuby.
Availability allows you to collect AsciiDoctor documentation that is part of a Java project (which we actively use). At the same time, AsciiDoctor and JRuby are downloaded automatically by Maven, and AsciiDoctor runs in the JRuby environment: you don't need to install anything on the machine! (Excluding the package graphviz, which is needed if you want to use GraphViz or PlantUML graphics.) Just put your .adoc files in the folder src/main/asciidoc/. Here , which collects slides with diagrams.
Convert slides to PDF
Although the HTML version of the slides is quite self-sufficient, it is still necessary to have a PDF version of the slides. Firstly, it happens that at some conferences that do not provide the speaker with the opportunity to connect their own laptop, they require slides βstrictly in pptx or pdf formatβ, not expecting that they are also in HTML. Secondly, it is good practice to send the organizers an unmodified version of your slides as they were shown at the report in PDF format for publication in the conference materials.
Fortunately, the Node.js utility handles this task. based on - Chrome browser management automation systems. You can convert a RevealJS presentation to PDF with the command
node decktape.js -s 3200x1800 --slides 1-500
reveal "file:///index.html?fragments=true" slides.pdf Two tricks when launching decktape that I had to come up with through trial and error:
-
resolution via parameter
-smust be set with a double margin, otherwise there may be problems with the conversion results -
in the URL of the HTML version of the presentation, you must pass the parameter
?fragments=true, which will allow you to create a separate PDF page for each intermediate state of your slide (for example, five pages for five list items if they are shown one after the other). This will allow you to use such a PDF on its own as a presentation during a report.
Automatic assembly and publishing on the web
It is convenient when slides are built automatically when changes get into the version control system, and even more convenient when automatically compiled slides are posted on the Internet for general use. Internet slides can be easily played in front of an audience from any machine connected to the Internet and a projector.
Since we use GitHub in our work, the natural choice of a CI system is , and for hosting ready-made presentations - . The idea behind github.io is that any static content placed on a branch gh-pages your project on GitHub becomes available at <Π²Π°ΡΠ΅ ΠΈΠΌΡ>.gihub.io/<Π²Π°Ρ ΠΏΡΠΎΠ΅ΠΊΡ>.
Complete TravisCI configuration file, including compiling the HTML version of the page using Maven, converting to PDF using decktape, and uploading the results to a branch gh-pages for publishing on github.io, looks like .
To build such a project on the TravisCI side, you need to set up environment variables
GH_REF- value of the form github.com/inponomarev/csa-hbGH_TOKEN- GitHub access token. You can get it in GitHub in your profile settings, Developer Settings -> Personal Access Tokens. If you upload a presentation to a public repository, then for this token it is enough to specify the only access level "Access public repositories".GH_USER_EMAIL/GH_USER_NAMEβ name/mail pair, on behalf of which the push to the branch will be carried outgh-pages.
Thus, each commit of the presentation code on GitHub leads to the automatic rebuilding of slides in HTML and PDF formats and re-uploading them to github.io. (Of course, you only need to post to github.io those presentations that you want to eventually make public.)
Project examples
Finally, links to a couple of example presentation projects with customized Maven scripts and CI configuration for Travis-CI, which can be cloned and used to create your own presentation projects:
-
(my report for JPoint 2019)
-
(my report for Heisenbug 2019)
Farewell PowerPoint! I don't think I'll ever need you for technical presentations π
Source: habr.com