r 输出自动生成文件
我被要求为我当地大学的下一学期设计新课程。 从历史上看,我使用Power Point创建课程幻灯片,并使用Word创建实验说明。 对于幻灯片和文档,还有其他可能的替代方法:
- Google幻灯片
- 一堆JavaScript框架( Reveal.js , Impress.js等)
- 专用的在线学习平台( Moodle等)
- 等等
我最近还使用Asciidoctor(使用Git版本)编写了一些实验室文档。 构建过程会生成HTML页面,并将它们托管在GitHub页面上。 每次按下都会触发构建。
该解决方案对我来说有几个优点:
- 我完全控制媒体。 Asciidoctor文件保存在我的硬盘驱动器上,以及我想要的其他任何Git存储库,无论是公共的还是私有的,都存储在云中或自托管。
- 该Asciidoctor格式编写的文档真的很棒。
- 与一个源文件中,可以有多种输出格式(.eg HTML,PDF等)。
- 托管在Github / GitLab Pages上HTML可以自动生成,用于遥控器上的每次推送。
初始点
建立
对于课程和实验,设置略有不同。
培训班
要显示幻灯片,让我们使用Reveal.js。 幸运的是, Asciidoctor Reveal.js允许从Asciidoctor源生成幻灯片。 使用Ruby,由于文档的原因,设置非常简单:
- 安装捆绑器:
geminstall bundler
- 创建具有以下内容的
Gemfile
:source 'https://rubygems.org' gem 'asciidoctor-revealjs'
- 配置捆绑器:
bundle config--local github.https true bundle --path= .bundle/gems --binstubs= .bundle/.bin
- 最后,生成HTML:
bundleexec asciidoctor-revealjs source.adoc
实际上,在我的情况下,生成命令略有不同:
bundleexec asciidoctor-revealjs -D output/cours \ (1)
-arevealjs_history=true\ (2)
-arevealjs_theme= white (3)
-arevealjs_slideNumber=true\ (4)
-a linkcss \ (5)
-acustomcss= ../style.css \ (6)
-arevealjsdir= https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.5.0 (7)
cours/ * .adoc (8)
- 设置HTML输出目录
- 在每个导航步骤中将URL明确推入浏览器历史记录中
- 使用白色(默认情况下为黑色)
- 显示幻灯片编号-仅供参考
- 创建一个外部CSS文件,而不是将样式嵌入到每个文档中-如果存在多个文档,则很有意义
- 覆盖某些样式
- 引用要使用JavaScript框架-可以是本地位置
- 生成属于一个文件夹的所有文档-而不只是一个特定的文档
实验室
从Asciidoctor生成标准HTML文档更加容易:
bundleexec asciidoctor -D output/tp tp/ * .adoc
自动远程生成
本地自动化
到目前为止,一切都很好。 一切正常,每次按遥控器都会生成该站点。 唯一的缺点是,为了预览该站点,必须要么推...要么每次都键入整个命令行。 bash历史记录会有所帮助,直到需要其他命令为止。
作为用户,我想自动预览HTML,以免我一遍又一遍地编写相同的命令行。
这一点比较困难,因为它与Asciidoctor不相关。 带有LiveReload的完善解决方案和所有功能都可能会被视为过大(请看我太懒了)。 但是,我对监视本地文件系统以及检测到更改时的命令触发感到非常满意。 当我的笔记本电脑在OSX上运行时,这是一个“可以在我的机器上工作”的解决方案。 这基于启动的过程和plist格式。
这种格式基于XML,但是“弱类型”并且基于元素的顺序。 例如,键值对的定义如下:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plistversion="1.0">
<dict>
<key> key1 </key>
<string> value1 </string>
<key> key2 </key>
<string> value2 </string>
</dict>
我必须自己找出几件事-我以前没有关于launchd的经验:
-
.plist
文件应按照名为Label
的键命名。 - 它应该位于
~/Library/LaunchAgents/
文件夹中。 - 在这种特定情况下,最重要的部分是了解如何监视文件系统 。 这是通过与要观察的路径数组关联的
WatchPaths
键实现的。 - 第二个最重要的部分是要执行的命令
ProgramArguments
。 语法非常复杂:命令行上的每个参数(用空格分隔)应该是数组中的一个元素。$ PATH似乎没有使用我自己用户的环境变量初始化,因此应使用可执行文件的完整路径。
- 由于调试是强制性的-至少在运行前几次时,请随时使用
StandardErrorPath
和StandardOutPath
分别在文件中写入标准err和out。
最终的.plist
看起来像这样:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plistversion="1.0">
<dict>
<key> Label </key>
<string> ch.frankel.generatejaveecours.plist </string>
<key> WorkingDirectory </key>
<string> /Users/frankel/projects/course/javaee </string>
<key> Program </key>
<string> /usr/local/bin/bundle </string>
<key> ProgramArguments </key>
<array>
<string> /usr/local/bin/bundle </string>
<string> exec </string>
<string> asciidoctor-revealjs </string>
<string> -a </string>
<string> revealjs_history=true </string>
<string> -a </string>
<string> revealjs_theme=white </string>
<string> -a </string>
<string> revealjs_slideNumber=true </string>
<string> -a </string>
<string> linkcss </string>
<string> -a </string>
<string> customcss=../style.css </string>
<string> -a </string>
<string> revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.5.0 </string>
<string> cours/*.adoc </string>
</array>
<key> WatchPaths </key>
<array>
<string> /Users/frankel/projects/course/javaee/cours </string>
</array>
<key> StandardErrorPath </key>
<string> /tmp/asciidocgenerate.err </string>
<key> StandardOutPath </key>
<string> /tmp/asciidocgenerate.out </string>
</dict>
</plist>
要最终启动守护程序 ,请使用launchctl
命令:
launchctl load ~/Library/LaunchAgents/ch.frankel.generatejaveecours.plist
结论
虽然在每次推送时自动生成HTML页面非常简单,但是在推送之前预览HTML需要手动操作。 但是,通过一些研究,可以扫描文件系统上的更改并在笔记本电脑上自动生成。 以懒惰为荣!
翻译自: https://blog.frankel.ch/automating-generation-asciidoctor-output/
r 输出自动生成文件