Geekly articles weekly

演示为代码，或者为什么我不再使用Powerpoint


看来我有机会为我的IT事业为同事，客户和公开场合做过许多演讲。 多年来，Powerpoint作为制作幻灯片的一种方式对我来说一直是自然而可靠的选择。 但是今年情况发生了质的变化。 从2月到5月，我有机会在五次会议上发表演讲，报告的幻灯片必须在很短的时间内准备好，但是要高质量。 出现了将幻灯片的视觉设计委托给他人的那部分工作的问题。 有一次我尝试通过邮件与.pptx文件一起与设计师合作，但是工作变得混乱了：没人知道幻灯片的哪个版本是“最新的”，而由于我们计算机上Powerpoint版本和字体的不同，布局也没有“通过”。 。 我决定尝试一些新的东西。 我尝试过，从那时起，我不认为会返回Powerpoint。


我们想要什么


大约一年半前，我们公司拒绝使用Word来创建项目文档，但面临着同样的问题：尽管Word可以很好地键入小型文档，但是随着数量的增长，在协作以及获得高质量和统一设计方面存在困难。 我们的选择落在了AsciiDoctor上 ，并且我们不会因为这种选择而欣喜若狂 ，但这是另一篇文章的主题。 大约在同一时间，我们了解了“一切都作为代码”的DevOps原则之一的有效性，因此，对于创建演示幻灯片的新技术的要求选择非常明显：


  1. 演示文稿应该是使用标记语言的纯文本文件。
  2. 我们有关于开发项目的幻灯片，因此标记应允许您轻松插入而无需借助外部系统
    • 语法突出显示的代码片段，
    • 通过箭头连接的几何形状形式的简单图表，
    • UML图表，流程图等。
  3. 演示项目应存储在版本控制系统中。
  4. 成品幻灯片的验证和组装应在CI系统中进行。

如今，有两种用于以标记语言创建幻灯片的基本选项：用于LaTeX的Beamer软件包或用于创建HTML / CSS幻灯片的框架之一（ RevealJS ， remark ， deck.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 update\n+ 13 warnings"] r0[shape=point, width = 0] r1 -> r0[ arrowhead = none, label="master branch" ]; r0-> r2 []; b1 -> b4; r1->b1 r1[label="150\nwarnings"] b1[label="± 0\nwarnings"] b4[label="± 0\nwarnings"] b4->r2 r2[label="163\nwarnings", color="red", xlabel=<<font color="red">merge blocked</font>>] {rank = same; u; r0; b4;} } -----

结果


顺便说一下，在Graphviz在线页面上可以方便地进行Graphviz实验和调试图片。


最后，如果您需要在幻灯片中插入方框图，类图或其他标准化图，则可以拯救与AsciiDoctor集成的另一个系统PlantUML。 我的同事Nikolai Potashnikov写了一篇有关PlantUML强大功能的单独文章 。


通过将演示文稿项目转换为存储在版本控制系统中的代码，可以组织演示文稿上的联合工作，首先，可以将创建内容和设计的任务分开。 RevealJS中的幻灯片（字体，背景，缩进）的设计是使用CSS描述的。 这个GIF可以最好地传达我的CSS技能，但是当有人使用CSS比我更敏捷，更快时，这并不令人害怕。 结果，事实证明，在快速接近演示文稿截止日期的情况下，我们可以通过Git同时处理不同的文件，并提高了通过邮件发送.pptx文件时无法实现的协作速度。


用幻灯片构建HTML页面


纯文本源很棒，但是如何将它们编译为演示文稿本身呢？


AsciiDoctor是一个Ruby项目，您可以通过多种方式运行它。 首先，您可以安装Ruby语言并直接运行asciidoctor，这可能是最接近Ruby开发人员的。


如果您不想参与Ruby的安装，则可以使用docker image asciidoctor / docker-asciidoctor ，可以通过VOLUME将项目源文件夹连接到其中，并在指定位置获取结果。


我选择的选项似乎有些出乎意料，但是对于我作为Java开发人员而言，这最方便。 它不需要安装Ruby或docker，但是允许您使用Maven脚本生成幻灯片。


事实是， JRuby项目（Ruby语言的Java实现）是如此出色，以至于您几乎可以在Java机器上运行为Ruby创建的所有内容，并且运行AsciiDoctor是最常见的JRuby应用程序之一。


asciidoctor-maven-plugin的存在使您可以收集AsciiDoctor文档，该文档是Java项目（我们正在积极使用）的一部分。 同时，Maven自动下载AsciiDoctor和JRuby，并且在JRuby环境中执行AsciiDoctor：无需在计算机上安装任何东西！ （除了graphviz软件包，如果要使用GraphViz或PlantUML图形，则需要此软件包。）只需将.adoc文件放入src/main/asciidoc/ 。 这是一个采摘场收集图表幻灯片的示例 。


将幻灯片转换为PDF


尽管幻灯片的HTML版本是完全自给自足的，但是仍然需要PDF版本的幻灯片。 首先，碰巧在一些没有为演讲者提供连接自己的笔记本电脑功能的会议上，他们要求幻灯片“严格以pptx或pdf格式”，而不期望它们也采用HTML。 其次，这是一种很好的形式，可以将组织者的幻灯片按报告中显示的格式发送给PDF格式的未更改版本，以便在会议资料中发布文件。


幸运的是，Node.js是一个基于Puppeteer （Chrome浏览器自动化系统）构建的decktape实用程序，可处理此任务。 您可以使用以下命令将RevealJS演示文稿转换为PDF


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

制作纸带的两个技巧必须通过反复试验才能得出：


  • 通过-s参数设置的分辨率必须设置为双精度，否则转换结果可能会出现问题


  • 您需要在演示文稿的HTML版本的URL中传递参数?fragments=true ，这将允许您为幻灯片的每个中间状态创建一个单独的PDF页面（例如，五个列表项的五个页面，如果它们一个接一个地显示）。 这样便可以将此类PDF本身用作报告中的演示文稿。



自动构建并发布到网络上


当更改落入版本控制系统中时自动收集幻灯片非常方便，而将自动编译的幻灯片发布到Internet上以供一般使用时更加方便。 来自互联网的幻灯片可以很容易地在连接到互联网和投影仪的任何机器上在观众面前“播放”。


由于我们在工作中使用GitHub，因此CI系统的自然选择是TravisCI ，它是托管现成演示文稿的imtqy.com 。 imtqy.com的想法是，放置在GitHub上项目的gh-pages分支中的任何静态内容都可以通过< >.gihub.io/< > 。


完整的TravisCI配置文件，包括使用Maven编译页面的HTML版本，使用decktape转换为PDF以及将结果上载到gh-pages分支以在imtqy.com上发布，包括以下内容 。


为了在TravisCI方面构建这样的项目，您需要配置环境变量


  • GH_REF表格github.com/inponomarev/csa-hb的值
  • GH_TOKEN -GitHub访问令牌。 您可以在GitHub上的个人资料设置（开发人员设置->个人访问令牌）中获取它。 如果将演示文稿上载到公共存储库，则对于此令牌，足以指定唯一的访问级别“访问公共存储库”。
  • GH_USER_EMAIL / GH_USER_NAME名称/邮件对，将代表他们执行gh-pages分支的推送。

因此，每次在GitHub上提交演示文稿代码，都会自动重建HTML和PDF格式的幻灯片并将其重新加载到imtqy.com上。 （当然，只有那些您想最后公开的演示文稿才应该上传到imtqy.com。）


项目实例


最后，有指向演示项目示例的链接，这些示例项目具有针对Travis-CI的自定义Maven脚本和CI配置，您可以在创建自己的演示项目时克隆并使用它们：



再见PowerPoint！ 我认为我永远不需要您进行技术演示：-)

Source: https://habr.com/ru/post/zh-CN456032/

More articles:


All Articles