🥇Prezentáció mint kód, avagy miért nem használom többé a Powerpoint-t

Úgy tűnik, hogy pályafutásom során tucatnyi prezentációt készítettem kollégák, megrendelők és nyilvános előadások számára az IT területén. Sokáig a PowerPoint volt a megszokott és megbízható választásom a diák elkészítésére. De idén a helyzet lényegesen megváltozott. Februártól májusig ötször szólítottak meg konferenciákon, és a prezentációs diák szakszerű elkészítése sürgős volt, miközben magas színvonalú feladatokat kellett végezni. Felmerült a kérdés, hogy a diákkészítés vizuális dizájn részét másoknak kellene delegálnom. Egyszer megpróbáltam együtt dolgozni egy dizájnerrel, .pptx fájlokat küldözgetve e-mailben, de a munka káosszá változott: senki sem tudta, hogy melyik diaverzió a „legújabb”, és a formázás egymásnak ellentmondott a PowerPoint verziók és a gépeinken található betűtípusok közötti eltérés miatt. Így úgy döntöttem, hogy kipróbálok valami újat. Kipróbáltam, és azóta nem tervezem visszatérni a PowerPoint-hoz.

Mit szeretnénk

Másfél éve cégünknél lemondtunk a Word használatáról a projekt dokumentáció elkészítésére, szembesülve a hasonló problémákkal: bár a Word jó egy kis dokumentum megírásához, a terjedelmesebb dokumentumok esetén a közös munka és a minőségi, egységes megjelenés megszerzése nehézségekbe ütközik. Mi a AsciiDoctor, és ezt a döntést azóta is örömmel fogadjuk, de ez egy külön téma. Körülbelül akkor tettünk szert a DevOps egyik alapelvének, az „everything as code” hatékonyságára, így a prezentációs diák előállításához szükséges új technológia kiválasztása meglehetősen magától értetődő volt:

A prezentációnak egy sima szövegfájlnak kell lennie egy jelölőnyelven.
A diák a fejlesztési projektekről szólnak, így a jelölésnek lehetővé kell tennie, hogy könnyedén, külső rendszerek igénybevétele nélkül beilleszthessük
- kódprojekteket szintaxiskiemeléssel,
- egyszerű diagramokat geometriai alakzatokból, nyilakkal összekötve,
- UML-diagramokat, folyamatábrákat és egyebeket.
A prezentáció projektjének verziókezelő rendszerben kell tárolódnia.
A kész diák validálását és összeszerelését CI-rendszerben kell elvégezni.

Ma két alapvető lehetőség létezik a diáknak jelölőnyelveken történő elkészítésére: a beamer a LaTeX-hez, vagy egyik keretrendszer HTML/CSS diák elkészítésére (RevealJS, remark, deck.js és sok más).

Bár a lelkem a LaTeX-hez vonzódik, az ész azt sugallta, hogy a választott megoldás, amelyet nemcsak én fogok használni, inkább egy ismertebb megoldás legyen. A LaTeX-et nem mindenki ismeri, és ha a mindennapi gyakorlatod nem kapcsolódik tudományos cikkek írásához, valószínűleg nincs időd belemerülni ennek a rendszerenek a bonyolult világába.

Azonban a HTML/CSS ismerete sem mondható, hogy széles körben elterjedt készség: én például nem ismerem teljesen. Szerencsére ebben az AsciiDoctor segít, amely egy átalakító. asciidoctor-revealjs lehetővé teszi RevealJS-diák létrehozását AsciiDoctor jelöléssel. Ez pedig egyszerűen tanulható és mindenki számára elérhető!

Hogyan lehet diát kódolni

A diákkódolás lényegének megértéséhez a legegyszerűbb konkrét példákat hozni. Mindegyik valódi diából származik, amelyet az idei konferenciákra készítettem.

Dia címmel és a fokozatosan megjelenő tételekkel:

== Miért van szükségünk a Streams API-ra?

[%step]
* Valós idejű stream feldolgozás
* Stream-szerű API (map / reduce)
* A motorháztető alatt:
** Automatikus offset commit
** Újraelosztás
** Kezelők belső állapota
** Könnyű skálázás

Eredmény

Cím és a szintaxis kiemelésével ellátott forráskód részlet:

== Kafka Streams API: a KStreams-alkalmazás általános felépítése

[source,java]
----
StreamsConfig config = ...;
//Itt állítjuk be a különböző opciókat

Topology topology = new StreamsBuilder()
//Itt építjük fel a topológiát
....build();
----

Eredmény

A beszéd kikészítése során a bemutató kódpéldák többször is átdolgozásra és javításokra kerülnek, ezért rendkívül hasznos, hogy gyorsan másolhatom és beilleszthetem a „nyers kódot” közvetlenül a diára, biztosítva a demó példája aktualitását, anélkül, hogy a szintaxis kiemelésével foglalkoznék.

Cím, illusztráció és szöveg (a diára való elrendezést cellákban végezzük AsciiDoctor táblázatok):

== Kafka Streams in Action

[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
“Kafka Streams in Action”, November 2018
* Kódpéldák a Kafka 1.0-hoz
|===

Eredmény

Néha a címre nincs szükség, de az elképzelésed illusztrálásához szükséged van egy egyszerű, teljes képernyőn megjelenő képre:

[%notitle]
== Nehéz a legacy-ban élni

image::swampman.jpg[canvas, size=cover]

Eredmény

Gyakran a gondolatot szükséges egy egyszerű diagrammal alátámasztani, amely „négyzetekből, nyilakkal összekapcsolva” áll. Szerencsére az AsciiDoctor integrálva van a rendszerrel. Graphviz — nyelvet, amely lehetővé teszi grafikus diagramok leírását a csúcsok és az azok közötti kapcsolatok alapján. A Graphviz-t el kell sajátítani, de a meglévő példák alapján ez meglehetősen egyszerű! Íme, hogyan néz ki ez:

== Készítünk „Bet Totalling App”

Mennyi a kifizetések összege a megtett tétek alapján, ha a kimenet játszik?

[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="Helyi Bolt"; fixedsize="true"; width="1.5"]
Source -> MapVal -> Sum -> Sink
Sum -> Store [dir=both; label=" n "]
{rank = same; Store; Sum;}
}
-----

Eredmény

Ha szükséges a figura feliratának szerkesztése, a nyíl irányának megváltoztatása stb. — ezt közvetlenül a prezentációs kódban lehet megtenni, ahelyett, hogy valahol újra megrajzolnánk a képet és ismét beillesztenénk a diára. Ez jelentősen növeli a diák készítésének sebességét.

Bonyolultabb példa:

== Nem reprodukálható összesítés
[graphviz, "unstable-update.png"]
-----
digraph G {
  rankdir="LR";
  graph [ dpi = 150 ];
  u -> r0;
  u[shape=plaintext; label="linter updaten+ 13 figyelmeztetés"]
  r0[shape=point, width = 0]
  r1 -> r0[ arrowhead = none, label="master branch" ];
  r0-> r2 [];   b1 -> b4;  r1->b1
  r1[label="150 figyelmeztetés"]
  b1[label="± 0 figyelmeztetés"]
  b4[label="± 0 figyelmeztetés"]
  b4->r2
  r2[label="163 figyelmeztetés", color="red", xlabel=<merge blocked>]
  {rank = same; u; r0; b4;}
}
-----

Eredmény

Egyébként kísérletezni a Graphviz-szal és a képek hibakeresése kényelmesen történik a Graphviz online.

Végül, ha egy blokkdiagramot, osztálydiagramot vagy más standardizált diagramot kell beilleszteni a diába, akkor egy másik, az AsciiDoctorral integrált rendszer is segíthet, PlantUML. A PlantUML széleskörű lehetőségeiről kollégám, Nikolaj Potasnyikov írt külön cikke erről a témáról, de valami ilyesmi:.

A prezentációs projekt kódra való átalakítása, amely a verziókezelő rendszerben tárolódik, lehetővé teszi a közös munkát a prezentáción, elsősorban a tartalom előállításának és a dizájn elválasztását. A RevealJS diáinak megjelenése (betűtípusok, háttér, margók) CSS segítségével van leírva. Az én személyes CSS kezelésének képességét legjobban ez a gif tükrözi ez a gif — de nem probléma, amikor vannak olyan emberek, akik sokkal ügyesebben és gyorsabban dolgoznak a CSS-sel, mint én. Így végül, a prezentáció határideje gyors közeledtével, párhuzamosan tudunk dolgozni különböző fájlokon a Git-en keresztül, és olyan együttműködési sebességet fejleszthetünk, ami lehetetlen lenne a .pptx fájlok e-mailben való elküldésével.

HTML-oldal összegyűjtése diákból

A sima szövegforrások nagyszerűek, de hogyan lehet őket a prezentációba összeállítani?

Az AsciiDoctor egy Ruby nyelven írt projekt, amelyet többféleképpen futtathatunk. Először is, telepítheti a Ruby nyelvet, és közvetlenül futtathatja az asciidoctort, ami valószínűleg legközelebb áll a Ruby fejlesztőkhöz.

Ha nem szeretne foglalkozni a Ruby telepítésével, használhatja a docker képet. asciidoctor/docker-asciidoctor, amelynek futtatásakor a VOLUME-on keresztül csatlakoztathatja a projekt forrásfájljaival rendelkező mappát, és a megadott helyen megkapja az eredményt.

Az a megoldás, amelyen megálltam, kissé váratlanul hangozhat, de nekem mint Java fejlesztőnek a legkényelmesebb. Nem igényel Ruby telepítést, sem Docker meglétét, viszont lehetővé teszi a diák generálását Maven szkripttel.

A lényeg az, hogy a projekt JRuby — a Ruby nyelv Java megvalósítása — annyira jó, hogy szinte mindent képes futtatni, ami Ruby-ra lett tervezve, és az AsciiDoctor futtatása az egyik leggyakoribb JRuby alkalmazás.

A asciidoctor-maven-plugin lehetővé teszi az AsciiDoctor dokumentáció összeállítását, amely a Java projekt részét képezi (ezt aktívan használjuk). Az AsciiDoctor és a JRuby automatikusan letöltődik a Maven által, és az AsciiDoctor a JRuby környezetében fut: semmit nem kell telepíteni a gépre! (Kivéve a csomagot graphviz, amely szükséges, ha GraphViz vagy PlantUML grafikákat szeretne használni.) Elég, ha az .adoc fájljait a következő mappába helyezi: src/main/asciidoc/. Itt példa egy emlékműre, amely diákat gyűjt össze diagramokkal.

A diák konvertálása PDF formátumba

Bár a diák HTML verziója teljesen önálló, néha szükség van a PDF változatra is. Először is, előfordul, hogy bizonyos konferenciákon, amelyek nem biztosítanak lehetőséget a saját laptop csatlakoztatására, a diák "szigorúan pptx vagy pdf formátumban" való bemutatását követelik, nem várva el, hogy azok HTML formátumban is léteznek. Másodszor, jó szokás, ha a szervezőknek megküldjük a diák nem módosított változatát, ahogyan az a prezentáción bemutatásra került, PDF formátumban az anyagok publikálásához.

Szerencsére, ezt a feladatot egy Node.js eszköz decktape, amely a Puppeteer -en alapul, a Chrome böngésző automatizálási rendszerén. A RevealJS prezentáció PDF-be konvertálása az alábbi paranccsal lehetséges:

node decktape.js -s 3200x1800 --slides 1-500 
  reveal "file:///index.html?fragments=true" slides.pdf

Két trükk a decktape futtatása során, amelyekre a próbák és hibák módszerével jöttem rá:

felbontás paraméterrel -s dupláznos tartalmat kell megadni, különben problémák merülhetnek fel a konverzió eredményeivel kapcsolatban
a HTML-verzió URL-jében meg kell adni egy paramétert ?fragments=true, amely lehetővé teszi, hogy külön PDF-oldalak készüljenek minden egyes közbülső állapot számára a diáján (például öt oldal öt listapont számára, ha azok egymás után jelennek meg). Ez lehetővé teszi, hogy ez a PDF önállóan használható legyen prezentációként egy előadás során.

Automatikus összeállítás és közzététel az interneten

Kényelmes, ha a diák automatikusan összeállnak, amikor változások történnek a verziókezelő rendszerben, és még ennél is kényelmesebb, ha az automatikusan összeállított diák online elérhetők a közönség számára. Az internetről származó diák könnyen "lejátszhatók" egy előadás során bármely gépről, amely csatlakozik az internethez és a projektorhoz.

Mivel GitHub-ot használunk a munkánk során, a CI-rendszer természetes választása TravisCI, a kész prezentációk hosztolására pedig github.io. A github.io ötlete az, hogy bármely statikus tartalom, amely a gh-pages ágbana Github-projektedbe kerül, elérhetővé válik a címen .github.io/.

A teljes TravisCI konfigurációs fájl, amely tartalmazza a HTML-verzió előállítását Maven segítségével, a PDF-be való konvertálást decktape segítségével és az eredmények feltöltését a gh-pages a github.io közzétételéhez, így néz ki így.

Egy ilyen projekt TravisCI általi összeállításához szükséges környezeti változók konfigurálása

GH_REF — a github.com/inponomarev/csa-hb formátumú érték
GH_TOKEN — GitHub-hoz való hozzáférési token. A GitHub profilod beállításainál a Developer Settings -> Personal Access Tokens alatt kapható. Ha a prezentációdat nyilvános tárolóba töltöd fel, akkor ennek a tokennek elegendő, ha egyetlen jogosultsági szintet állítasz be "Hozzáférés a nyilvános tárolókhoz".
GH_USER_EMAIL / GH_USER_NAME — a név/email pár, amelyből a push a branch-re történik gh-pages.

Így minden kódváltozás a prezentációhoz a GitHub-on automatikus újraépítést eredményez HTML és PDF formátumokban, és ezek feltöltését a github.io-ra. (Természetesen csak azokat a prezentációkat érdemes feltölteni a github.io-ra, amelyeket végül nyilvánossá kívánsz tenni.)

Projektpéldák

Végül is itt van néhány példa a prezentációs projektekhez készült Maven-scriptekről és Travis-CI konfigurációról, amelyeket klónozhatsz és felhasználhatsz saját prezentációs projektjeid létrehozásához: