🥇示範為程式碼，或為什麼我不再使用 Powerpoint

我想在我的 IT 職業生涯中，我已經向同事、客戶進行了數十次演示和公開演講。多年來，Powerpoint 作為幻燈片製作工具一直是我自然而可靠的選擇。但今年情況發生了質的變化。從二月到五月，我有機會在五次會議上發言，報告的幻燈片必須在短時間內準備好，但品質要高。出現了將幻燈片視覺設計部分工作委託給其他人的問題。我曾經嘗試與設計師合作，通過郵件發送 .pptx 文件，但工作變得混亂：沒有人知道哪個版本的幻燈片是“最新”的，並且由於 Powerpoint 的差異，佈局“移動”我們機器上的版本和字體。我決定嘗試一些新的東西。我嘗試過，從那時起我就沒有想過再回到Powerpoint了。

我們想要什麼

大約一年半前，我們公司停止使用Word創建專案文檔，也遇到了同樣的問題：雖然Word適合列印小文檔，但隨著文檔量的增加，協作和獲得高品質和高品質的文檔變得困難。統一設計。我們的選擇落到了 ASCII醫生，我們永遠為這個選擇感到高興，但這是另一篇文章的主題。大約在同一時間，我們了解到「一切皆程式碼」的 DevOps 原則之一的有效性，因此創建簡報投影片的新技術的要求選擇非常明顯：

簡報必須是標記語言的純文字檔案。
我們的幻燈片是關於開發項目的，因此標記應該使其易於插入，而無需求助於外部系統
- 帶有語法高亮的程式碼片段，
- 箭頭連接的幾何形狀形式的簡單圖表，
- UML 圖、流程圖等。
簡報草稿必須儲存在版本控制系統中。
成品幻燈片的驗證和組裝應在 CI 系統中完成。

如今，用標記語言建立投影片有兩個基本選項：投影儀用於 LaTeX 或使用 HTML/CSS 建立投影片的框架之一（揭示JS, 備註, 甲板.js 和許多其他）。

雖然我的靈魂在於 LaTeX，但我的想法決定，我不是唯一使用的解決方案的選擇應該是更廣泛的人熟悉的解決方案。並不是每個人都了解 LaTeX，如果你的日常練習與寫科學文章無關，那麼你不太可能有時間沉浸在這個系統龐大、複雜的世界。

然而，掌握 HTML/CSS 並不是一項普遍的技能：例如，我還遠遠沒有完全精通它。幸運的是，我們已經熟悉的 AsciiDoctor 來幫忙了：轉換器 asciidoctor Revealjs 允許您使用 AsciiDoctor 標記建立 RevealJS 幻燈片。而且它很容易學習，每個人都可以使用！

如何編寫投影片程式碼

要理解 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 進行實驗和調試圖像很方便圖形視覺化在線.

最後，如果您需要在幻燈片中插入流程圖、類別圖或其他標準化圖表，那麼與 AsciiDoctor 整合的另一個系統可以幫助您，植物UML。我的同事 Nikolai Potashnikov 撰寫了有關 PlantUML 廣泛功能的文章單獨的帖子.

將簡報專案轉換為儲存在版本控制系統上的程式碼使得組織簡報的共同工作成為可能，首先，將創建內容和設計的任務分開。 RevealJS 中投影片的設計（字體、背景、縮排）是使用 CSS 描述的。我個人的 CSS 技能最好的表達方式是這個動圖 - 但當有人比我更靈活、更快地使用 CSS 時，這並不可怕。結果表明，隨著簡報截止日期的臨近，我們可以透過 Git 同時處理不同的文件，並提高透過郵件發送 .pptx 檔案時不可能實現的協作速度。

使用幻燈片建立 HTML 頁面

純文字來源很棒，但如何將它們編譯到簡報本身？

AsciiDoctor 是一個用 Ruby 編寫的項目，有多種方法來運行它。首先，你可以安裝Ruby語言並直接執行asciidoctor，這可能是最接近Ruby開發者的了。

如果你不想安裝 Ruby，你可以使用 docker 映像 asciidoctor/docker-asciidoctor，啟動後，您可以透過 VOLUME 將資料夾與專案來源連接起來，並在給定位置取得結果。

我選擇的選項可能看起來有些出乎意料，但對於我作為 Java 開發人員來說，這是最方便的。它不需要安裝 Ruby 或 docker，但允許您使用 Maven 腳本產生幻燈片。

重點是這個項目紅寶石 - Ruby 語言的 Java 實作非常好，它允許您在 Java 機器中運行為 Ruby 創建的幾乎所有內容，而運行 AsciiDoctor 是 JRuby 最常見的用途之一。

可用性 asciidoctor-maven-插件讓您收集屬於 Java 專案（我們積極使用的專案）一部分的 AsciiDoctor 文件。同時，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

推出 Decktape 時我們必須透過反覆試驗想出的兩個技巧：

透過參數解析 -s 必須指定兩倍邊距，否則轉換結果可能會出現問題
在簡報的 HTML 版本的 URL 中，您需要傳遞一個參數 ?fragments=true，這將為投影片的每個中間狀態建立一個單獨的 PDF 頁面（例如，如果依序顯示五個項目符號點，則五個頁面）。這將允許您在報告期間單獨使用此類 PDF 作為簡報。

自動組裝並發佈到網路上

當版本控制系統發生變更時，自動編譯幻燈片會很方便，而當自動編譯的幻燈片發佈到網路上供公眾使用時，會更方便。來自網路的幻燈片可以透過任何連接到網路的機器和投影機輕鬆地在觀眾面前「播放」。

由於我們在工作中使用 GitHub，因此 CI 系統的自然選擇是特拉維斯CI，以及舉辦現成的簡報 - github.io。 github.io 背後的想法是，發佈到分支的任何靜態內容 gh-pages 您在 GitHub 上的專案的詳細信息，可在以下位置取得： <ваше имя>.gihub.io/<ваш проект>.

完整的TravisCI設定文件，包括使用Maven編譯頁面的HTML版本，使用decktape轉換為PDF，以及將結果上傳到線程 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。）