🥇Predstavitev kot koda, ali zakaj ne uporabljam več Powerpoint-a

Zdi se, da sem v svoji IT karieri pripravil na desetine predstavitev za sodelavce, naročnike in javna nastopanja. Dolga leta je bil PowerPoint zame naravna in zanesljiva izbira za izdelavo diapozitivov. Vendar se je letos situacija močno spremenila. Od februarja do maja sem nastopil na petih konferencah, diapozitive pa sem moral pripraviti v kratkem času, vendar kakovostno. Pojavilo se je vprašanje, komu zaupati del dela, ki se nanaša na vizualno oblikovanje diapozitivov. Enkrat sem poskusil delati s oblikovalcem, tako da sem mu pošiljal datoteke .pptx po pošti, vendar se je delo spremenilo v kaos: nihče ni vedel, katera različica diapozitivov je „najbolj nova“, oblikovanje pa se je pokvarilo zaradi razlik v različicah PowerPointa in pisavah na naših računalnikih. Odločil sem se poskusiti nekaj novega. Poskusil sem, in od takrat ne mislim več vrniti se k PowerPointu.

Kaj želimo

Približno leto in pol nazaj smo v podjetju prenehali uporabljati Word za pripravo projektne dokumentacije, ker smo naleteli na enake težave: čeprav je Word dober za pripravo majhnega dokumenta, z naraščanjem obsega nastanejo težave s skupnim delom in doseganjem kakovostne in enotne oblike. Naša izbira je padla na AsciiDoctor, in temu smo izjemno veseli, a to je tema za poseben članek. Približno takrat smo spoznali učinkovitost enega od DevOps principov „everything as code“, zato je bila izbira zahtev za novo tehnologijo ustvarjanja predstavitvenih diapozitivov precej očitna:

Predstavitev mora biti besedilna datoteka v oznakah.
Diapozitivi se nanašajo na projekte razvoja, zato mora oznaka omogočiti enostavno vstavljanje
- kodo z označevanjem sintakse,
- preproste diagrame v obliki geometrijskih oblik, povezanih s puščicami,
- UML-diagrame, blokovne diagrame in še več.
Projekt predstavitve mora biti shranjen v sistemu za nadzor različic.
Validacija in sestavljanje končnih diapozitivov mora potekati v CI-sistemu.

Trenutno sta na voljo dva osnovna načina za ustvarjanje diapozitivov v označevalnih jezikih: paket beamer za LaTeX ali enega od okvirjev za ustvarjanje diapozitivov na HTML/CSS (RevealJS, remark, deck.js in še mnogi drugi).

Čeprav je moja duša naklonjena LaTeX-u, mi je razum govoril, da naj bi bil izbor rešitve, ki jo ne bom uporabljal samo jaz, bolj znan širokemu krogu ljudi. LaTeX ni znan vsem, in če vaša vsakodnevna praksa ni povezana s pisanjem znanstvenih člankov, potem verjetno ne boste imeli časa, da bi se poglobili v ogromen in zapleten svet tega sistema.

Kljub temu pa obvladovanje HTML/CSS ni prav pogosto razširjena veščina: jaz je na primer ne obvladam v polni meri. Na srečo pa je tukaj že znan AsciiDoctor: pretvornik, asciidoctor-revealjs omogoča ustvarjanje RevealJS diapozitivov z uporabo AsciiDoctor označevanja. In to je preprosto za učenje ter dostopno vsakomur!

Kako kodirati diapozitive

Za razumevanje bistva kodiranja diapozitivov v AsciiDoctor je najlažje prikazati konkretne primere. Vsi so iz dejanskih diapozitivov, ki sem jih pripravil za svoje konferenčne predstavitve letos.

Diapozitiv z naslovom in seznamom, pri čemer se točke odpirajo ena za drugo:

== Zakaj potrebujemo Streams API?

[%step]
* Obdelava podatkov v realnem času
* API, podoben toku (map/reduce)
* Pod pokrovom:
** Samodejno potrjevanje offsetov
** Ponovno uravnoteženje
** Notranje stanje obdelovalnikov
** Enostavno skaliranje

Результат.

Naslov in del izvorne kode s poudarjeno sintakso:

== Kafka Streams API: splošna struktura KStreams aplikacije

[source,java]
----
StreamsConfig config = ...;
// Tukaj nastavimo različne možnosti

Topology topology = new StreamsBuilder()
// Tukaj gradimo topologijo
....build();
----

Результат.

Med pripravo na predstavitev se demonstracijski primeri kode večkrat predelujejo in izboljšujejo, zato je neprecenljiva možnost hitro kopirati in prilepiti "surovo kodo" neposredno v diapozitiv, s čimer zagotavljamo aktualnost demo primera in ne skrbimo za poudarjeno sintakso.

Naslov, ilustracija in besedilo (razporeditev po diapozitivu izvajamo v celicah tabel AsciiDoctor):

== Kafka Streams in Action

[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
“Kafka Streams in Action”, november 2018
* Primeri kode za Kafka 1.0
|===

Результат.

Včasih naslov ni potreben, ampak le ilustracija vaše misli, potrebna je preprosta slika po celotnem ekranu:

[%notitle]
== Življenje v dediščini ni enostavno

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

Результат.

Pogosto je potrebno preprosto misliti podkrepiti s preprosto diagramo, v obliki "kvadratov, povezanih z puščicami". Na srečo je AsciiDoctor integriran s sistemom Graphviz — jezik, ki omogoča opisovanje grafičnih diagramov na podlagi opisov vozlišč in povezav med njimi. Graphviz je treba obvladati, vendar je na podlagi že obstoječih primerov to razmeroma enostavno! Tako to izgleda:

== Pisanje "Bet Totalling App"

Kakšen je skupni znesek izplačil za opravljene stave, če se izide? 

[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;}
}
-----

Результат.

V primeru, ko je potrebno urediti oznako na predmetu, spremeniti smer puščice itd., se to lahko stori neposredno v kodi predstavitve, namesto da bi risali sliko nekje drugje in jo znova vstavili v diapozitiv. To znatno povečuje hitrost dela na diapozitivih.

Primer nekoliko bolj zapleten:

== Neponovljiva sestava
[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=<merge blocked>]
  {rank = same; u; r0; b4;}
}
-----

Результат.

Sicer, eksperimentiranje z Graphvizom in odpravljanje težav s slikami je priročno na strani Graphviz online.

Nazadnje, če je potrebno vstaviti v diapozitiv blokovni diagram, diagram razredov ali drugo standardizirano shemo, lahko tukaj pomaga še en integriran sistem z AsciiDoctor, PlantUML. O širokih možnostih PlantUML je moj kolega Nikolaj Potashnikov napisal poseben prispevek.

Pretvorba projekta predstavitve v kodo, shranjeno v sistemu za nadzor različic, omogoča organizacijo skupnega dela na predstavitvi, predvsem pa ločitev nalog ustvarjanja vsebine in oblikovanja. Oblikovanje diapozitivov (pisave, ozadja, odmiki) v RevealJS se opisuje s pomočjo CSS. Moje osebno obvladovanje CSS najbolje ponazori ta gif — a to ni strašno, ko imamo ljudi, ki delajo s CSS veliko bolj spretno in hitreje od mene. Na koncu dobimo, da v razmerah hitro bližajoče se roka za predstavitev lahko hkrati delamo na različnih datotekah preko Gita in povečujemo hitrost sodelovanja, ki je nemogoča pri pošiljanju datotek .pptx po elektronski pošti.

Sestava HTML-strani s diapozitivi

Navadne besedilo-izvori so super, a kako jih združiti v samo predstavitev?

AsciiDoctor je projekt napisan v Ruby-ju in ga je mogoče zagnati na več načinov. Najprej, lahko namestite Ruby jezik in zaženete asciidoctor neposredno, kar bo verjetno najbližje Ruby razvijalcem.

Če se ne želite ukvarjati z namestitvijo Ruby-ja, lahko uporabite docker sliko asciidoctor/docker-asciidoctor, ki vam omogoča, da povežete mapo z izvorno kodo projekta preko VOLUME pri zagonu in na določenem mestu pridobite rezultat.

Možnost, na kateri sem se ustavil, se vam morda zdi nekoliko presenetljiva, a je zame kot Java razvijalca najbolj priročna. Ne zahteva namestitve Ruby-ja, niti prisotnosti dockerja, prav tako pa omogoča generiranje diapozitivov s pomočjo Maven skripta.

Gre za to, da je projekt JRuby — Java realizacija Ruby jezika — tako dobra, da omogoča zagon skoraj vsega, kar je ustvarjeno za Ruby, v Java napravi, pri čemer je zagon AsciiDoctorja eno izmed najpogostejših uporabe JRuby-ja.

Postojanje asciidoctor-maven-plugin omogoča sestavljanje dokumentacije AsciiDoctor, ki je del Java projekta (kar aktivno uporabljamo). Pri tem se AsciiDoctor in JRuby avtomatsko preneseta s strani Mavena, AsciiDoctor pa se izvaja v okolju JRuby: ničesar ni treba namestiti na napravo! (Razen paketa graphviz, ki je potreben, če želite uporabljati grafiko GraphViz ali PlantUML.) Dovolj je, da svoje .adoc datoteke postavite v mapo src/main/asciidoc/. Tukaj je primer pomnika, ki sestavlja diapozitive z diagrami.

Pretvorba diapozitivov v PDF

Čeprav je HTML različica diapozitivov povsem samostojna, je včasih potrebno imeti tudi PDF različico diapozitivov. Prvič, zgodi se, da na nekaterih konferencah, kjer govorniku ni omogočeno povezovanje lastnega prenosnika, zahtevajo diapozitive 'strogo v formatu pptx ali pdf', ne pričakujoč, da so lahko tudi v HTML-ju. Drugič, dobra praksa je, da organizatorjem pošljete neizbežen primer vaših diapozitivov v obliki, kot so bili predstavljeni na predavanju, v PDF formatu za objavo datoteke v gradivu konference.

Na srečo to nalogo opravi orodje Node.js decktape, zgrajeno na osnovi Puppeteer — sistema za avtomatizacijo upravljanja s Chrome brskalnikom. Pretvorba RevealJS predstavitve v PDF je mogoča z ukazom

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

Dve triki pri zagonu decktape, do katerih sem prišel z metodo poskusov in napak:

ločenost prek parametra -s treba postaviti sa dvostrukom rezervom, inače mogu doći do problema sa rezultatima konverzije
u URL-u HTML verzije prezentacije treba preneti parametar ?fragments=true, što će omogućiti kreiranje posebne PDF stranice za svako međustanje vašeg slajda (na primer, pet stranica za pet stavki na listi, ako se prikazuju jedna za drugom). To će omogućiti korišćenje takvog PDF-a samostalno kao prezentacije tokom izlaganja.

Automatska izrada i objavljivanje na webu

Praktično je kada se slajdovi automatski prikupljaju prilikom promene u sistemu upravljanja verzijama, a još je bolje kada se automatski napravljeni slajdovi postave na internet za opštu upotrebu. Slajdove sa interneta lako je „prikazati“ pred publikom sa bilo kog računara povezanog na internet i projektor.

Pošto koristimo GitHub u našoj praksi, prirodni izbor CI sistema je TravisCI, a za hosting gotovih prezentacija — github.io. Ideja github.io je da je svaki statički sadržaj stavljen u granu gh-pages vašeg projekta na GitHub-u dostupan na adresi .gihub.io/.

Puni konfiguracioni fajl TravisCI, koji uključuje kompajliranje HTML verzije stranice koristeći Maven, konverziju u PDF pomoću decktape i upload rezultata u granu gh-pages za objavljivanje na github.io, izgleda tako.

Za izradu takvog projekta na strani TravisCI potrebno je postaviti varijable okruženja

GH_REF — vrednost oblika github.com/inponomarev/csa-hb
GH_TOKEN — token za pristup GitHub-u. Može se dobiti u GitHub-u u podešavanjima svog profila, Developer Settings -> Personal Access Tokens. Ako objavljujete prezentaciju u javnom repozitorijumu, za ovaj token je dovoljno postaviti jedinu nivo pristupa „Access public repositories“.
GH_USER_EMAIL / GH_USER_NAME — par ime/email, u čije ime će se izvršiti push u granu gh-pages.

Dakle, svaki commit koda prezentacije na GitHub-u dovodi do automatizovane rekonstrukcije slajdova u HTML i PDF formatima i ponovnog postavljanja na github.io. (Naravno, na github.io treba da se postave samo one prezentacije koje želite konačno učiniti javnim.)

Primeri projekata

Za konec — povezave na nekaj primerov projektov predstavitev z ustreznimi Maven skripti in CI konfiguracijo za Travis-CI, ki jih lahko klonirate in uporabite pri oblikovanju lastnih projektov predstavitev: