מצגת כקוד, או למה אני לא משתמש יותר ב-Powerpoint

אני חושב שהעברתי עשרות מצגות לעמיתים, לקוחות ודיבור בפני קהל בקריירת ה-IT שלי. במשך שנים רבות, Powerpoint הייתה עבורי בחירה טבעית ואמינה ככלי לייצור שקפים. אבל השנה המצב השתנה מבחינה איכותית. מפברואר עד מאי הזדמן לי לנאום בחמישה כנסים, ואת השקופיות לדוחות היה צורך להכין בזמן קצר, אך באיכות גבוהה. עלתה השאלה לגבי האצלת חלק זה של העבודה הנוגע לעיצוב החזותי של השקופיות לאנשים אחרים. פעם ניסיתי לעבוד עם מעצב, לשלוח קבצי .pptx בדואר, אבל העבודה הפכה לכאוס: אף אחד לא ידע איזו גרסה של השקופיות היא "החדשה ביותר", והפריסה "זזה" בגלל ההבדל ב-Powerpoint גרסאות וגופנים במכונות שלנו. והחלטתי לנסות משהו חדש. ניסיתי את זה, ומאז לא חשבתי לחזור ל-Powerpoint.

מה אנחנו רוצים

לפני כשנה וחצי החברה שלנו הפסיקה להשתמש ב-Word ליצירת תיעוד פרויקטים, לאחר שנתקלה באותן בעיות: למרות ש-Word טוב להקלדת מסמך קטן, ככל שהנפח גדל, נוצרים קשיים בשיתוף פעולה וקבלת איכות גבוהה עיצוב מאוחד. הבחירה שלנו נפלה על AsciiDoctor, ואנחנו לא מפסיקים לשמוח על הבחירה הזו, אבל זה נושא למאמר נפרד. בערך באותו זמן, למדנו את היעילות של אחד מעקרונות ה-DevOps של "הכל כקוד", כך שהבחירה בדרישות לטכנולוגיה החדשה ליצירת שקופיות מצגת הייתה די ברורה:

1. המצגת חייבת להיות קובץ טקסט רגיל בשפת סימון.
2. השקפים שלנו עוסקים בפרויקטי פיתוח, כך שהסימון אמור להקל על ההכנסה, מבלי להזדקק למערכות חיצוניות
   • קטעי קוד עם הדגשת תחביר,
   • דיאגרמות פשוטות בצורה של צורות גיאומטריות המחוברות בחצים,
   • דיאגרמות UML, תרשימי זרימה ועוד.
3. יש לאחסן את טיוטת המצגת במערכת בקרת גרסאות.
4. אימות והרכבה של שקופיות מוגמרות צריך להיעשות במערכת CI.

כיום, קיימות שתי אפשרויות בסיסיות ליצירת שקופיות בשפות סימון: חבילה מכה עבור LaTeX או אחת מהמסגרות ליצירת שקופיות באמצעות HTML/CSS (לחשוף את JS, הֶעָרָה, deck.js ורבים אחרים).

למרות שהנשמה שלי טמונה ב-LaTeX, דעתי הכתיבה שהבחירה בפתרון שלא אהיה היחיד שישתמש בו צריכה להיות בצד של פתרון המוכר למעגל רחב יותר של אנשים. לא כולם מכירים את LaTeX, ואם התרגול היומיומי שלך אינו קשור לכתיבת מאמרים מדעיים, לא סביר שיהיה לך זמן לטבול את עצמך בעולם הענק והמורכב של המערכת הזו.

עם זאת, שליטה ב-HTML/CSS היא לא בדיוק מיומנות רווחת: אני, למשל, רחוק מלהיות בקי בה באופן מלא. למרבה המזל, AsciiDoctor המוכר ממילא בא להציל: ממיר אסקיידוקטור-מגלה מאפשר לך ליצור שקופיות RevealJS באמצעות סימון AsciiDoctor. וזה קל ללמוד ונגיש לכולם!

כיצד לקודד שקופיות

כדי להבין את המהות של קידוד שקופיות ב-AsciiDoctor, הדרך הקלה ביותר היא לתת דוגמאות ספציפיות. כל אלה הם ממשקפים שהכנתי עבור מצגות הכנס שלי השנה.

שקופית עם כותרת ורשימה בפריטים הנפתחים בזה אחר זה:

== Зачем нам Streams API?

[%step]
* Real-time stream processing
* Stream-like API (map / reduce)
* Под капотом:
** Автоматический offset commit
** Ребалансировка
** Внутреннее состояние обработчиков
** Легкое масштабирование

תוצאה

קטע כותרת וקוד מקור עם הדגשת תחביר:

== Kafka Streams API: общая структура KStreams-приложения

[source,java]
----
StreamsConfig config = ...;
//Здесь устанавливаем всякие опции

Topology topology = new StreamsBuilder()
//Здесь строим топологию
....build();
----

תוצאה

כהכנה להרצאה, הדגמות קוד עוברות תיקונים ושיפורים חוזרים ונשנים, כך שהיכולת להעתיק ולהדביק במהירות את ה"קוד הגולמי" ישירות לשקופית היא חשובה מאין כמותה, מה שמבטיח שההדגמה מעודכנת מבלי לדאוג להדגשת תחביר.

כותרת, איור וטקסט (הפריסה בשקופית נעשית בתאים טבלאות AsciiDoctor):

== Kafka Streams in Action

[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
“Kafka Streams in Action”, November 2018
* Примеры кода для Kafka 1.0
|===

תוצאה

לפעמים אין צורך בכותרת, וכדי להמחיש את הנקודה שלך אתה רק צריך תמונה במסך מלא:

[%notitle]
== Жить в легаси нелегко

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

תוצאה

לעתים קרובות רעיון צריך להיתמך על ידי דיאגרמה פשוטה, בצורה של "ריבועים מחוברים בחצים". למרבה המזל, AsciiDoctor משולב עם המערכת Graphviz — שפה המאפשרת לך לתאר דיאגרמות גרפים על סמך תיאור הקודקודים והקשרים ביניהם. Graphviz לוקח עקומת למידה, אבל בהתבסס על הדוגמאות שסופקו, זה די קל לעשות! כך זה נראה:

== Пишем “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;}
}
-----

תוצאה

במקרה בו יש צורך לערוך את הכיתוב באיור, לשנות את כיוון החץ וכו', ניתן לעשות זאת ישירות בקוד המצגת, במקום לצייר מחדש את התמונה איפשהו ולהכניסה מחדש לשקופית. זה מגביר באופן משמעותי את מהירות העבודה על שקופיות.

דוגמה יותר מסובכת:

== Невоспроизводимая сборка
[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;}
}
-----

תוצאה

אגב, זה נוח להתנסות ב-Graphviz ולאפות באגים בתמונות בעמוד Graphviz באינטרנט.

לבסוף, אם אתה צריך להכניס תרשים זרימה, דיאגרמת מחלקה או תרשים סטנדרטי אחר לשקופית, אז מערכת אחרת המשולבת עם AsciiDoctor יכולה לבוא להציל, PlantUML. עמיתי ניקולאי פוטשניקוב כתב על היכולות הנרחבות של PlantUML פוסט נפרד.

הפיכת פרויקט המצגת לקוד המאוחסן במערכת בקרת גרסאות מאפשרת לארגן עבודה משותפת על המצגת, קודם כל, להפריד בין משימות יצירת התוכן והעיצוב. עיצוב השקופיות (גופנים, רקעים, הזחות) ב-RevealJS מתואר באמצעות CSS. המיומנות האישית שלי עם CSS מועברת בצורה הטובה ביותר על ידי הגיף הזה - אבל זה לא מפחיד כשיש אנשים שעובדים עם CSS בצורה הרבה יותר מיומנת ומהירה ממני. כתוצאה מכך, מסתבר שעם דד-ליין שמתקרב במהירות למצגת, אנו יכולים לעבוד על קבצים שונים בו זמנית באמצעות Git ולפתח מהירות שיתוף פעולה בלתי אפשרית בעת שליחת קבצי .pptx בדואר.

בניית דף HTML עם שקופיות

מקורות טקסט פשוטים הם נהדרים, אבל איך מרכיבים אותם למצגת עצמה?

AsciiDoctor הוא פרויקט שנכתב ברובי, וישנן מספר דרכים להפעיל אותו. ראשית, אתה יכול להתקין את שפת Ruby ולהפעיל את asciidoctor ישירות, וזה כנראה הדבר הכי קרוב למפתחי Ruby.

אם אתה לא רוצה להתעסק עם התקנת Ruby, אתה יכול להשתמש בתמונת docker asciidoctor/docer-asciidoctor, שלתוכו, בעת ההשקה, תוכל לחבר את התיקיה עם מקורות הפרויקט באמצעות VOLUME ולקבל את התוצאה במיקום נתון.

האפשרות שבחרתי אולי נראית קצת לא צפויה, אבל היא הכי נוחה לי כמפתח ג'אווה. זה לא דורש התקנה של Ruby או docker, אבל מאפשר לך ליצור שקופיות באמצעות סקריפט של Maven.

הנקודה היא שהפרויקט ג'רובי - הטמעת Java של שפת Ruby כל כך טובה שהיא מאפשרת להריץ כמעט כל דבר שנוצר עבור Ruby במכונת Java, והפעלת AsciiDoctor היא אחד השימושים הנפוצים ביותר של JRuby.

זמינות asciidoctor-maven-plugin מאפשר לך לאסוף תיעוד AsciiDoctor המהווה חלק מפרויקט Java (בו אנו משתמשים באופן פעיל). במקביל, AsciiDoctor ו-JRuby מורידים אוטומטית על ידי Maven, ו-AsciiDoctor פועל בסביבת JRuby: אין צורך להתקין שום דבר על המכונה! (לא כולל חבילה graphviz, הדרוש אם ברצונך להשתמש בגרפיקה של GraphViz או PlantUML.) פשוט מקם את קובצי ה-.adoc שלך בתיקייה src/main/asciidoc/. כאן דוגמה לפומניקאיסוף שקופיות עם דיאגרמות.

המרת שקופיות ל-PDF

למרות שגרסת ה-HTML של השקופיות די עצמאית, עדיין יש צורך בגרסת PDF של השקופיות. ראשית, קורה שבכמה כנסים שאינם מספקים לדובר את האפשרות לחבר את המחשב הנייד שלו, הם דורשים שקופיות "בפורמט pptx או pdf בלבד", מבלי לצפות שהם גם ב-HTML. שנית, טוב לשלוח למארגנים גרסה לא ערוכה של השקופיות שלך כפי שהוצגו בדוח, בפורמט PDF לפרסום הקובץ בחומרי הכנס.

למרבה המזל, כלי השירות Node.js מטפל במשימה זו. דיקטייפ, בנוי על בסיס מפעיל בובות - מערכות אוטומציה לניהול דפדפן Chrome. אתה יכול להמיר מצגת RevealJS ל-PDF עם הפקודה

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

שני טריקים בעת השקת קלטת, שהיינו צריכים להמציא באמצעות ניסוי וטעייה:

• רזולוציה באמצעות פרמטר -s יש לציין עם שוליים כפולים, אחרת עלולות להיות בעיות בתוצאות ההמרה

• בכתובת ה-URL של גרסת ה-HTML של המצגת אתה צריך להעביר פרמטר ?fragments=true, שייצור דף PDF נפרד עבור כל מצב ביניים של השקף שלך (לדוגמה, חמישה עמודים עבור חמש נקודות תבליטים אם הם מוצגים בזה אחר זה). זה יאפשר לך להשתמש ב-PDF כזה בפני עצמו כמצגת במהלך דוח.

הרכבה ופרסום אוטומטי באינטרנט

זה נוח כאשר שקופיות מקופלות אוטומטית כאשר מתבצעים שינויים במערכת בקרת הגרסאות, ועוד יותר נוח כאשר שקופיות מקופלות אוטומטית מתפרסמות באינטרנט לשימוש ציבורי. שקופיות מהאינטרנט ניתנות ל"ניגון" בקלות מול קהל מכל מכונה המחוברת לאינטרנט ומקרן.

מכיוון שאנו משתמשים ב-GitHub בעבודה שלנו, הבחירה הטבעית של מערכת CI היא TravisCI, ולאירוח מצגות מוכנות - github.io. הרעיון מאחורי github.io הוא שכל תוכן סטטי פורסם בסניף gh-pages של הפרויקט שלך ב-GitHub, הופך זמין ב- <ваше имя>.gihub.io/<ваш проект>.

קובץ תצורה מלא של TravisCI, כולל קומפילציה של גרסת ה-HTML של הדף באמצעות Maven, המרה ל-PDF באמצעות decktape, והעלאת התוצאות לשרשור gh-pages לפרסום ב-github.io, נראה כמו כך.

כדי לבנות פרויקט כזה בצד TravisCI, עליך להגדיר משתני סביבה

• GH_REF - ערך כמו github.com/inponomarev/csa-hb
• GH_TOKEN - אסימון גישה של GitHub. אתה יכול לקבל את זה מ-GitHub בהגדרות הפרופיל שלך, הגדרות מפתח -> אסימוני גישה אישיים. אם אתה מעלה מצגת למאגר ציבורי, אז בשביל האסימון הזה מספיק לציין את רמת הגישה היחידה "גישה למאגרים ציבוריים".
• GH_USER_EMAIL / GH_USER_NAME — זוג שם/אימייל שבשמו תתבצע הדחיפה לשרשור gh-pages.

לפיכך, כל התחייבות של קוד המצגת ב-GitHub גורמת לכך שהשקופיות נבנות אוטומטית מחדש בפורמטים של HTML ו-PDF ומועלים מחדש ל-github.io. (כמובן, עליך להעלות ל-github.io רק את המצגות שבסופו של דבר תרצה לפרסם.)

דוגמאות לפרויקטים

לבסוף, הנה קישורים לכמה דוגמאות לפרויקטי מצגת עם סקריפטים מותאמים אישית של Maven ותצורת CI עבור Travis-CI, שניתן לשכפל ולהשתמש בהם בעת יצירת פרויקטי מצגת משלך:

• https://github.com/inponomarev/kstreams-examples (ההרצאה שלי עבור JPoint 2019)

• https://github.com/inponomarev/csa-hb (הדוח שלי עבור Heisenbug 2019)

להתראות Powerpoint! אני לא חושב שאי פעם אזדקק לך למצגות טכניות :)

מקור: www.habr.com