Dit blyk dat ek tientalle aanbiedings vir kollegas, kliënte en redenaars gemaak het tydens my loopbaan in IT. Powerpoint is vir baie jare vir my 'n natuurlike en betroubare keuse as 'n skyfiemaakinstrument. Maar hierdie jaar het die situasie kwalitatief verander. Van Februarie tot Mei het ek die geleentheid gehad om by vyf konferensies te praat, en die skyfies vir die verslae moes in 'n kort tyd, maar met hoë gehalte, voorberei word. Die vraag het ontstaan oor die delegeer van daardie deel van die werk rakende die visuele ontwerp van die skyfies aan ander mense. Ek het eenkeer probeer om met 'n ontwerper te werk deur .pptx-lêers per pos te stuur, maar die werk het in chaos ontaard: niemand het geweet watter weergawe van die skyfies "die nuutste" is nie, en die uitleg was "dryf" as gevolg van verskille in die weergawes van Powerpoint en lettertipes op ons masjiene. En ek het besluit om iets nuuts te probeer. Ek het dit probeer, en sedertdien dink ek nie om terug te keer na Powerpoint nie.
Wat wil ons hê
Ongeveer 'n jaar en 'n half gelede het ons by die maatskappy die gebruik van Word vir die skep van ontwerpdokumente laat vaar, omdat ons dieselfde probleme ondervind het: hoewel Word goed is om 'n klein dokument te tik, word dit moeilik om saam te werk en hoë -kwaliteit en verenigde ontwerp. Ons keuse het geval , en ons hou nie op om ons te verheug oor hierdie keuse nie, maar dit is 'n onderwerp vir 'n aparte artikel. Ongeveer dieselfde tyd het ons die doeltreffendheid van een van die "alles as kode" DevOps-beginsels geleer, so die keuse van vereistes vir 'n nuwe tegnologie vir die skep van aanbiedingskyfies was redelik voor die hand liggend:
- Die aanbieding moet 'n gewone tekslêer in 'n opmerktaal wees.
- Ons skyfies handel oor ontwikkelingsprojekte, so die opmaak behoort jou in staat te stel om maklik, sonder om na eksterne stelsels toe te vlug, in te voeg
- kodebrokkies met sintaksuitlig,
- eenvoudige diagramme in die vorm van meetkundige vorms wat deur pyle verbind word,
- UML-diagramme, vloeidiagramme en meer.
- Die aanbiedingsprojek moet in weergawebeheer gehou word.
- Validasie en samestelling van voltooide skyfies moet in 'n CI-stelsel gedoen word.
Vandag is daar twee basiese opsies om skyfies in opmaaktale te skep: vir LaTeX of een van die raamwerke vir die skep van skyfies in HTML/CSS (, , en vele ander).
Alhoewel my siel by LaTeX lê, het my verstand vir my gesê dat die keuse van 'n oplossing wat ek nie alleen sal gebruik nie, aan die kant van 'n oplossing moet wees wat aan 'n wyer kring van mense bekend is. Nie almal ken LaTeX nie, en as jou daaglikse praktyk nie verband hou met die skryf van wetenskaplike artikels nie, is dit onwaarskynlik dat jy tyd sal hê om in die groot ingewikkelde wêreld van hierdie stelsel te duik.
Die kennis van HTML / CSS is egter nie 'n alomteenwoordige vaardigheid nie: ek besit dit byvoorbeeld nie ten volle nie. Gelukkig kom die reeds bekende AsciiDoctor hier tot die redding: converter laat jou toe om RevealJS-skyfies te skep met AsciiDoctor-opmaak. En dit is maklik om te leer en toeganklik vir almal!
Hoe om skyfies te enkodeer
Om die essensie van AsciiDoctor-skyfiekodering te verstaan, is dit die maklikste om spesifieke voorbeelde te gee. Almal van hulle is van werklike skyfies wat ek vir my konferensiepraatjies hierdie jaar gemaak het.
'n Skyfie met 'n titel en 'n lys in paragrawe wat een na die ander oopmaak:
== Зачем нам Streams API?
[%step]
* Real-time stream processing
* Stream-like API (map / reduce)
* Под капотом:
** Автоматический offset commit
** Ребалансировка
** Внутреннее состояние обработчиков
** Легкое масштабированиеGevolg
Kop- en bronkode-brokkie met sintaksis-uitlig:
== Kafka Streams API: общая структура KStreams-приложения
[source,java]
----
StreamsConfig config = ...;
//Здесь устанавливаем всякие опции
Topology topology = new StreamsBuilder()
//Здесь строим топологию
....build();
----Gevolg
Tydens die voorbereiding van die verslag word die kode-demo's herhaaldelik herwerk en verbeter, dus die vermoë om die "rou kode" vinnig direk in die skyfie te kopieer en te plak, om die relevansie van die demo te verseker en nie bekommerd te wees oor sintaksis-uitlig nie, is van onskatbare waarde.
Titel, illustrasie en teks (ons voer die uitleg op die skyfie in selle uit ):
== Kafka Streams in Action
[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
“Kafka Streams in Action”, November 2018
* Примеры кода для Kafka 1.0
|===Gevolg
Soms het jy nie 'n titel nodig nie, maar net 'n volskermprent is nodig om jou idee te illustreer:
[%notitle]
== Жить в легаси нелегко
image::swampman.jpg[canvas, size=cover]Gevolg
Dikwels moet 'n gedagte ondersteun word deur 'n eenvoudige diagram, in die vorm van "vierkante verbind deur pyle." Gelukkig is AsciiDoctor met die stelsel geïntegreer - 'n taal wat jou toelaat om grafiekdiagramme te beskryf gebaseer op die beskrywing van die hoekpunte en die verbande tussen hulle. Graphviz moet bemeester word, maar op grond van die beskikbare voorbeelde is dit redelik maklik om te doen! Hier is hoe dit lyk:
== Пишем “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;}
}
-----Gevolg
In die geval wanneer jy die byskrif op die figuur moet wysig, verander die rigting van die pyltjie, ens. - dit kan direk in die aanbiedingskode gedoen word, in plaas daarvan om die prentjie iewers oor te teken en dit weer in die skyfie in te voeg. Dit verhoog die spoed van werk op skyfies aansienlik.
Meer ingewikkelde voorbeeld:
== Невоспроизводимая сборка
[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;}
}
-----Gevolg
Terloops, eksperimenteer met Graphviz en ontfouting van prente is gerieflik op die bladsy .
Ten slotte, as jy 'n vloeidiagram, klasdiagram of ander gestandaardiseerde diagram in 'n skyfie moet invoeg, dan kan 'n ander stelsel geïntegreer met AsciiDoctor tot die redding kom, . My kollega Nikolai Potashnikov het geskryf oor die uitgebreide moontlikhede van PlantUML .
Om 'n aanbiedingsprojek te omskep in kode wat op 'n weergawebeheerstelsel gestoor word, maak dit moontlik om gesamentlike werk op 'n aanbieding te organiseer, eerstens om die take van die skep van inhoud en ontwerp te skei. Die ontwerp van skyfies (lettertipes, agtergronde, opvulling) in RevealJS word met behulp van CSS beskryf. My persoonlike vaardigheid met CSS word die beste oorgedra - maar dit is nie skrikwekkend as daar mense is wat baie meer behendig en vinniger met CSS werk as ek nie. Die slotsom is dat met die vinnig naderende aanbiedingsperdatum, ons gelyktydig aan verskillende lêers deur Git kan werk en 'n samewerkende spoed ontwikkel wat onmoontlik is wanneer .pptx-lêers per pos gestuur word.
Bou 'n HTML-bladsy met skyfies
Gewone teksbronne is wonderlik, maar hoe stel jy dit saam in die aanbieding self?
AsciiDoctor is 'n projek wat in Ruby geskryf is en daar is verskeie maniere om dit te begin. Eerstens kan u die Ruby-taal installeer en asciidoctor direk bestuur, wat waarskynlik die naaste is wat Ruby-ontwikkelaar kan kry.
As jy nie met jou Ruby-installasie wil mors nie, kan jy die docker-beeld gebruik , waarin jy, wanneer dit van stapel gestuur is, die gids met die projekbronne via VOLUME kan koppel en die resultaat op die gespesifiseerde plek kan kry.
Die opsie wat ek gekies het, lyk dalk ietwat onverwags, maar dit is die gerieflikste vir my as 'n Java-ontwikkelaar. Dit vereis nie dat Ruby of docker geïnstalleer word nie, maar laat jou toe om skyfies te genereer met behulp van 'n Maven-skrif.
Die punt is dat die projek - Die Java-implementering van die Ruby-taal is so goed dat dit jou toelaat om byna alles wat vir Ruby geskep is in 'n Java-masjien te laat loop, en asciiDoctor is een van die mees algemene gebruike van JRuby.
Beskikbaarheid laat jou toe om AsciiDoctor-dokumentasie te versamel wat deel is van 'n Java-projek (wat ons aktief gebruik). Terselfdertyd word AsciiDoctor en JRuby outomaties deur Maven afgelaai, en AsciiDoctor loop in die JRuby-omgewing: jy hoef niks op die masjien te installeer nie! (Die pakkie uitgesluit graphviz, wat nodig is as jy GraphViz- of PlantUML-grafika wil gebruik.) Plaas net jou .adoc-lêers in die gids src/main/asciidoc/. hier , wat skyfies met diagramme versamel.
Skakel skyfies om na PDF
Alhoewel die HTML-weergawe van die skyfies redelik selfversorgend is, is dit steeds nodig om 'n PDF-weergawe van die skyfies te hê. Eerstens gebeur dit dat by sommige konferensies wat nie die spreker die geleentheid bied om hul eie skootrekenaar aan te sluit nie, hulle skyfies “streng in pptx- of pdf-formaat” benodig, en nie verwag dat dit ook in HTML is nie. Tweedens is dit goeie praktyk om vir die organiseerders 'n ongewysigde weergawe van jou skyfies te stuur soos dit in die aanbieding in PDF-formaat gewys is vir publikasie in die konferensiemateriaal.
Gelukkig hanteer die Node.js-hulpprogram hierdie taak. op die basis gebou - Chrome-blaaierbestuur-outomatiseringstelsels. U kan 'n RevealJS-aanbieding na PDF omskakel met die opdrag
node decktape.js -s 3200x1800 --slides 1-500
reveal "file:///index.html?fragments=true" slides.pdf Twee truuks met die bekendstelling van decktape waarmee ek deur proef en fout vorendag moes kom:
-
resolusie via parameter
-smoet met 'n dubbele marge gestel word, anders kan daar probleme met die omskakelingsresultate wees -
in die URL van die HTML-weergawe van die aanbieding, moet jy die parameter slaag
?fragments=true, wat jou sal toelaat om 'n aparte PDF-bladsy vir elke tussentoestand van jou skyfie te skep (byvoorbeeld vyf bladsye vir vyf lysitems as hulle een na die ander gewys word). Dit sal jou toelaat om so 'n PDF op sy eie as 'n aanbieding tydens 'n verslag te gebruik.
Outomatiese samestelling en publisering op die web
Dit is gerieflik wanneer skyfies outomaties gebou word wanneer veranderinge in die weergawebeheerstelsel kom, en selfs meer gerieflik wanneer outomaties saamgestelde skyfies op die internet geplaas word vir algemene gebruik. Internetskyfies kan maklik voor 'n gehoor gespeel word vanaf enige masjien wat aan die internet gekoppel is en 'n projektor.
Aangesien ons GitHub in ons werk gebruik, is die natuurlike keuse van 'n CI-stelsel , en vir die aanbieding van klaargemaakte aanbiedings - . Die idee agter github.io is dat enige statiese inhoud op 'n tak geplaas word gh-pages jou projek op GitHub word beskikbaar by <ваше имя>.gihub.io/<ваш проект>.
Voltooi TravisCI-konfigurasielêer, insluitend die samestelling van die HTML-weergawe van die bladsy met Maven, omskakeling na PDF met behulp van decktape, en die oplaai van die resultate na 'n tak gh-pages vir publisering op github.io, lyk .
Om so 'n projek aan die TravisCI-kant te bou, moet jy omgewingsveranderlikes opstel
GH_REF- waarde van die vorm github.com/inponomarev/csa-hbGH_TOKEN- GitHub-toegangtoken. Jy kan dit in GitHub kry in jou profielinstellings, Ontwikkelaarinstellings -> Persoonlike toegangtokens. As jy 'n aanbieding na 'n publieke bewaarplek oplaai, dan is dit vir hierdie teken genoeg om die enigste toegangsvlak "Toegang tot publieke bewaarplekke" te spesifiseer.GH_USER_EMAIL/GH_USER_NAME— naam/pos-paar, namens wie die stoot na die tak uitgevoer sal wordgh-pages.
Dus, elke commit van die aanbiedingskode op GitHub lei tot die outomatiese herbou van skyfies in HTML- en PDF-formate en die heroplaai daarvan na github.io. (Natuurlik hoef u slegs die aanbiedings wat u uiteindelik openbaar wil maak, op github.io plaas.)
Projek voorbeelde
Ten slotte, skakels na 'n paar voorbeeldaanbiedingsprojekte met pasgemaakte Maven-skrifte en CI-konfigurasie vir Travis-CI, wat gekloon en gebruik kan word om jou eie aanbiedingsprojekte te skep:
-
(my verslag vir JPoint 2019)
-
(my verslag vir Heisenbug 2019)
Vaarwel PowerPoint! Ek dink nie ek sal jou ooit nodig hê vir tegniese aanbiedings nie 🙂
Bron: will.com