开启 AsciiDoc 规范之旅

作者 Sarah White 和 Dan Allen -

在过去一年中，社区对 AsciiDoc 规范的呼声此起彼伏，很明显，大家已经准备好让 AsciiDoc 迈出这一步。我们也这么认为。我们还联系了 AsciiDoc 的创始人 Stuart，他也表示支持。所以，现在是时候着手此事了。

在 Eclipse Foundation 拥有新家

我们希望 AsciiDoc 能有一个光明的未来，并拥有发展壮大所需的资源。为了实现这一目标，我们决定向 Eclipse Foundation 提交一份 AsciiDoc 语言规范提案。Eclipse Foundation 为规范的制定提供了一个平台，并致力于透明和开源，这些价值观与 AsciiDoc 及其社区高度契合。Eclipse Foundation 规范流程 (EFSP) 提供了一个清晰但可自定义的结构，降低了流程停滞的风险，并确保了结果在实际世界中的可用性。该流程是公开的、供应商中立的，所有源材料和最终产物都是开源的。

AsciiDoc 成为规范意味着什么？

AsciiDoc 语言规范将包括一个开源的规范文档，其中定义了必需和可选的 API 定义、语义行为、数据格式和协议，以及一个开源的技术兼容性套件 (TCK)，开发人员可以使用它来开发和测试兼容的实现。（熟悉 Asciidoctor 的 Dan 和我的人都知道，一个开源的 TCK 是我们的硬性要求）。根据 EFSP 的定义，兼容的实现必须完全实现规范版本的所有非可选元素，必须满足相应 TCK 的所有要求，并且不得更改指定的 API。

对于用户和开发者来说，AsciiDoc 规范都将意味着一个清晰、可用的 AsciiDoc 定义及其解释方式。开发者将能够围绕 AsciiDoc 构建实现、工具和服务，而不会有稀释其含义或分裂它的风险。反过来，用户将拥有更多的选择、更高的文档可移植性，并确保兼容的实现和工具能够按照版本化的规范处理他们的 AsciiDoc 文档。

Asciidoctor 将何去何从？

我们计划让 Asciidoctor (RubyGem) 成为 AsciiDoc (规范) 的独立、兼容的实现。（这并不意味着 Asciidoctor 的整体将迁移到 Eclipse Foundation）。为了通过 TCK 测试，这可能意味着 Asciidoctor 中需要添加、删除或更改功能，以满足规范的必需和可选元素。Asciidoctor.js 和 AsciidoctorJ 项目，如果他们选择这样做，也可以决定成为独立的、兼容的实现，并且拥有比以前更大的自由度。这将为新兴的实现将 AsciiDoc 带到更多平台腾出空间。

一旦规范流程开始进行，我们将了解更多信息，并及时向您通报预期情况。

准备好了吗？开始吧！

创建 AsciiDoc 规范的下一步是将其作为一个规范项目提交给 Eclipse Foundation。我和 Dan（作为 OpenDevise，代表 Asciidoctor）计划提交的提案将由 Eclipse 管理组织审查，然后发布供社区审查和评论。想了解更多关于规范流程的信息，我鼓励您查看 Wayne Beaton 的博文 第二部分：EFSP 和 第三部分：创建。规范流程是 Eclipse 开发流程 (EDP) 的一个分支，您可以在 第一部分：EDP 中阅读。您也可以阅读 EFSP 文档。

通过一个可以适应 AsciiDoc 社区需求的规范流程，我和 Dan 相信该语言将以可持续且实质性的方式发展，从而跟上社区当前和未来的需求。我们非常期待开始，希望您能加入我们，共同努力，让 AsciiDoc 成为一项规范！

AsciidoctorJ 1.6.0 发布，终于来了！

作者 Robert Panzer, Dan Allen 和 Sarah White -

经过数年的酝酿（或者说是桶陈？），我们终于发布了 AsciidoctorJ 1.6.0！相关构件可从 Bintray 和 Maven Central 获取。

AsciidoctorJ 是什么？

AsciidoctorJ 是在 JVM 上运行 Asciidoctor 的官方库。使用 AsciidoctorJ，您可以转换 AsciiDoc 内容，分析已解析的 AsciiDoc 文档的结构，并用 Java 和其他 JVM 语言编写 Asciidoctor 扩展。

在升级之前，您需要了解一些重要的事情，本文将对此进行介绍。虽然 AsciidoctorJ 仍然建立在强大的 Asciidoctor RubyGem 的基础上，但它已经发展成为一个独立的を有份的项目。此次发布为新老用户带来了稳定性和关键增强。请举杯，我们将为您带来所有细节。

迈向 SemVer 的重要里程碑

尽管版本号如此，这次发布应被视为一次重大发布。因此，它与 1.5.x 系列的发布不兼容。

AsciidoctorJ 1.6.0 是为了准备切换到语义化版本控制 (SemVer) 而进行的最后一次过渡性发布。我们将最后一次打破规则，但有充分的理由。考虑到 1.6.0 分支已经桶陈了很长时间，我们希望允许其被启用以收集反馈，并挖掘出意外的惊喜，然后再跳到 2.0.0 和 SemVer。如果一切顺利，我们预计 2.0.0 版本将在该版本之后不久发布。届时，我们将开始按照 SemVer 规则对 AsciidoctorJ 进行版本控制。

要了解更多关于 SemVer 以及它如何影响 Asciidoctor 项目的总体情况，请参阅 切换到语义化版本控制。

切换到 SemVer 也意味着 AsciidoctorJ 将独立于 Asciidoctor 进行版本控制。AsciidoctorJ 已经发展成为不仅仅是为 JVM 打包的 Asciidoctor RubyGem。它拥有完整的 API，包括基于 Java 的扩展以及与 Java 生态系统的紧密集成（例如，JUL、Ruby 对象桥接等）。其独立的版本线将允许它更快地发展，并帮助大家更好地理解每个版本将带来什么。最重要的是，它将解决导致 1.6.0 版本积压多年的情况。

新功能

主要的 API 和打包更改

自 AsciidoctorJ 诞生以来，我们对 JRuby 以及它如何桥接 Ruby 和 Java 对象有了很多了解。利用这些知识，我们彻底重新设计了底层集成，以解决原始设计中的不足。

这种重新设计需要我们对 API 进行破坏性更改，这对于 AsciidoctorJ 的持续发展是绝对必要的。但这同时也为我们提供了修复众多 Bug 的机会，而这些 Bug 在 1.5.x 系列中无法在不破坏兼容性的情况下修复。您会很高兴地得知，重新设计消除了在编写扩展或使用 1.5.x 版本导航文档模型时可能遇到的故障。

作为此更改的一部分，我们将 API 和实现类拆分为单独的包和 JAR，以对其进行适当的隔离。我们还通过映射 Asciidoctor 中的所有节点类型并移除 ContentPart 和 StructuredDocument API 来协调相互冲突的文档模型。请参阅 API 文档（api，impl）以了解可用的类型及其组织方式。

重构的扩展 API

得益于重新设计，基于 JRuby 的实现被更好地隐藏在 API 之后。特别是，API 中不再有 JRuby 的 RubyObject 类的引用。

抽象语法树 (AST) 的接口已完全重命名，以更好地表示其目的。例如，AbstractNode 接口已重命名为 ContentNode，AbstractBlock 已重命名为 StructuralNode，Inline 已重命名为 PhraseNode。Java 中映射了更多的 AST，包括列表和定义列表，以及用于在扩展处理器中创建表结构的辅助工具。

总的来说，扩展和 AST 的 API 应该感觉像是一个纯粹的 Java 库（例如，getAttr() 现在是 getAttribute()）。您甚至可以使用基于注释的配置（例如，@Name）来定义扩展处理器。

请查阅 集成器指南，了解所有相关信息并找到许多示例。

添加了转换器 API

引入了一个新的转换器 API，使得完全用 Java 实现自定义输出格式的转换器成为可能。此 API 允许您从 Java 扩展 Asciidoctor，类似于您已经通过扩展 API 所能做到的。您可以按照 转换器文档 来了解如何使用这个新 API。

事实上，已经有一个转换器使用此 API 从 Groovy 将 AsciiDoc 转换为 Leanpub 风格的 Markdown。

访问 Asciidoctor 的日志

当 Asciidoctor 在文档中遇到问题时，它会将错误和警告消息记录到 Ruby 日志记录器。将 Asciidoctor 集成到您自己的软件中时，捕获这些日志消息以便妥善处理非常重要。以前，这些消息是 AsciidoctorJ 无法触及的。现在情况已不再如此。新的 日志处理 API 会捕获 Asciidoctor 中记录的消息，并将它们路由到您自己的日志处理程序。

更好的文档

AsciidoctorJ 1.6.0 提供了扩展和经过测试的 文档，用于编写扩展和转换器。这些文档保证是正确的，因为它们会与每次提交一起测试 ;) 并且正在将文档整合到 Asciidoctor 的新 Antora 文档站点中。

有关此版本中发生的更改的更详细说明，请参阅 发布说明。请记住，由于 1.6.0 的开发与 1.5.x 并行了很长时间，因此 1.6.0 中的许多更改可能对您来说已经很熟悉了，因为它们已被反向移植到 1.5.x 发布系列中。

迁移说明

如果您只使用 Asciidoctor、Asciidoctor.Factory 和 *Builder 类（例如，Asciidoctor#convertFile），您可能无需更改代码。事实上，Asciidoctor Maven Plugin 和 Asciidoctor Gradle Plugin 已经支持此版本，主要是因为它们只依赖于公共的加载/转换 API。

AST 和扩展 API 的必要更改确实引入了破坏性更改，需要修改您现有的扩展。迁移扩展主要是为了符合新的 API。这主要包括切换 AST 接口的新名称，并与更新的方法签名保持一致。除了名称和签名更改之外，API 仍然应该是可识别的，因此与您现有的逻辑兼容。

以下是为 AsciidoctorJ 1.5.8 和 1.6.0 编写的几个扩展示例，以让您了解需要注意的更改类型：

如果您在迁移扩展或文档内省代码时遇到困难，请在 问题跟踪器 中提交问题，以便我们找到前进的道路。

Java 兼容性

Asciidoctor 1.6.0 最低需要 Java 8。它也能在 Java 11 上运行，并且已针对 Java 11 进行测试。

从 AsciidoctorJ 1.6.0 开始，该项目将遵循 Oracle 官方 Java SE 支持路线图 来确定其 Java 兼容性。虽然 AsciidoctorJ 不需要 Oracle Java SE，但该路线图可以作为判断哪些 Java 版本被认为是当前的有用参考。

Asciidoctor 1.6.0 尚不支持在模块路径上运行，这是 Java 9 中引入的 Java 平台模块系统 的一个关键特性。我们希望在即将发布的版本中实现这一点。然而，这将取决于 AsciidoctorJ 的依赖项（最重要的是 JRuby）在这方面的进展。尽管有此限制，您仍然可以在 Java 11 上运行 Asciidoctor 1.6.0。

致谢

我们想借此机会表彰几位关键人物，他们共同促成了这次发布的成功。

  • Jérémie Bresson，他发起将 API 和实现类分离，并现代化了 API 签名。

  • Abel Romero，他协助设计了 JUL 日志集成，并首先在 Maven 插件中进行了测试。

  • Frank Becker，他彻底改进和简化了 Gradle 构建。

  • Guillaume Grossetie，他对 API 和实现进行了大量清理和改进，并通过启动 AsciidoctorG 对重新设计进行了压力测试。

  • Charles Nutter、Thomas Enebo 以及 JRuby 团队，他们创建和维护了 AsciidoctorJ 所基于的 JRuby。

  • 最后，我们的“前辈” Alex Soto，他启动了 AsciidoctorJ 项目，并向我们展示了其潜在的可能性。

当然，还有许多其他人值得感谢。正如我们多次说过的，没有 众多志愿者 的辛勤工作和协作，这个项目是不可能实现的。所以，谢谢您！

2.0.0 的展望

破坏性更改尚未结束。在走向 2.0.0 的过程中，我们希望进一步拆分 AsciidoctorJ 的 API 和其实现。我们的主要目标是支持底层的替代实现，例如 Asciidoctor.js，使用相同的公共 API。

为了帮助我们达到 2.0.0，我们恳请您测试 1.6.0 版本，并告知我们您是否遇到任何问题或更改，这些更改妨碍您迁移到它。现在是时候在 2.0.0 版本发布之前将其做好。请在 问题跟踪器 中报告您发现的所有问题。

感谢您陪伴我们一起将 AsciiDoc 的精华带到 JVM。

切换到语义化版本控制

作者 Dan Allen -

经过多年的讨论，我们终于准备好在 Asciidoctor 中切换到语义化版本控制。这次切换将作为每个参与项目下一次重大发布的一部分。

关于语义化版本控制

语义化版本控制（或简称 SemVer）是一个基于简单的 MAJOR.MINOR.PATCH 顺序选择版本号的逻辑系统。

  • MAJOR 版本用于引入不兼容的更改（无论大小）。

  • MINOR 版本用于添加向后兼容的功能。

  • PATCH 版本用于修复 Bug（当然是向后兼容的）。

还可以通过构建元数据为预发布版本留出空间。您可以在 https://semver.org 上了解更多信息。

在我们当前的系统中，补丁发布与主版本和次版本发布无法区分，并且只有一个发布线。经验告诉我们（以艰难的方式），这种情况既不清晰也不可持续。对我们而言，SemVer 旨在实现更好的沟通和发展空间。它是一个基于共享期望和信任的系统。虽然它可能不完美，但 SemVer 应该有助于理解版本号的含义以及何时进行升级。我们不能期望它能防止破坏，但至少您会知道何时可能发生。

独立版本化项目

切换到 SemVer 也意味着 Asciidoctor 项目，即 Asciidoctor、AsciidoctorJ 和 Asciidoctor.js，将独立进行版本控制。生态系统中的其他项目也可能会开始独立版本化（事实上，有些已经开始了）。

AsciidoctorJ 和 Asciidoctor.js 都已经发展到远远超出重新分发 Asciidoctor RubyGem 的阶段。它们拥有自己的 API、扩展模型、自定义功能和平台集成。这值得拥有自己的版本线。独立的版本线还将使用户能够更好地理解每个版本将带来什么。

在与 Robert (AsciidoctorJ 负责人) 和 Guillaume (Asciidoctor.js 负责人) 交流后，这是我们商定的系统：

  • 核心处理器（Asciidoctor、AsciidoctorJ 和 Asciidoctor.js）将从 2.0.0 版本开始迁移到 SemVer。我们计划这三个项目同时进行这次主版本迁移，以最大限度地减少混淆。

  • 如果 Asciidoctor.js 或 AsciidoctorJ 需要对 Asciidoctor 进行更改，它们可以强制 Asciidoctor 发布。这意味着 Asciidoctor 必须随时“准备发布”。补丁或次要版本发布不需要太多讨论，但主版本发布自然需要。

  • 2.0.0 之后，我们不会尝试在三个项目之间统一版本号。Guillaume 提出了一个有力的论点，认为尝试统一版本号会违背 SemVer 的原则，从而导致版本号失去意义。这确实会增加记录 Asciidoctor.js 或 AsciidoctorJ 所提供底层 Asciidoctor 版本的复杂性。然而，AsciidoctorJ 和 Asciidoctor.js 都提供了访问底层 Asciidoctor 版本号的 API。发布号也可以通过 asciidoctor-version 文档属性访问。

我们考虑过在坚持 SemVer 的同时，如何将 Asciidoctor、AsciidoctorJ 和 Asciidoctor.js 锁定到同一版本。然而，我们得出的结论是，这样做只会延续我们看到的版本发布积压的状况。最好让这些项目拥有在适当时机自由发布的自由。有了三个版本号段 (MAJOR.MINOR.PATCH)，我们终于有了足够的空间来实现这些发布！

后续步骤

我们将首先将 Asciidoctor 1.5.8 版本重新打包为 2.0.0，并进行一些小的调整以放弃不再支持的 Ruby 版本。然后 AsciidoctorJ 和 Asciidoctor.js 将会跟进发布它们的 2.0.0 版本。届时，我们将严格按照上述 SemVer 规则进行版本控制。

开始使用 Asciidoctor 的工具

作者 Guillaume Scheibel and Maxime Gréau -

您刚刚发现了 Asciidoctor，并想知道从哪里开始才能高效地使用您的 AsciiDoc 文档？以下是生成与 AsciiDoc 内容相关的 HTML 代码的各种可能性。

DocGist：在线编辑器

DocGist 是一个 AsciiDoc 的在线编辑器，它允许您实时编辑文档并生成 HTML 预览，与其他用户共享您的文档，以及多人协作编辑同一份文档。此工具无需任何特定安装或账户创建。

它可以在 http://gist.asciidoctor.org 访问。

DocGist

浏览器扩展

通过简单的浏览器扩展，可以实时查看本地或远程 AsciiDoc 源码文件的 HTML 渲染。

Chrome 扩展

Chrome 的 Asciidoctor.js Live Preview 扩展还允许您选择预定义的主题或导入自己的自定义主题 (CSS)。

更多信息请参考 GitHub 项目 asciidoctor-chrome-extension。

Chrome Asciidoctor.js Live Preview

Firefox 插件

Firefox 的 Asciidoctor.js Live Preview 插件与其它扩展一样，提供实时 HTML 可视化。

要使用最新版本的插件，最好通过从 GitHub 下载最新发布版本来安装。

更多信息请参考 GitHub 项目 asciidoctor-firefox-addon。

Firefox Asciidoctor.js Live Preview

Opera 插件

由于 Chrome 扩展与 Opera 兼容，这个插件与 Chrome 的相同，因此提供相同的功能。

更多信息请参考 GitHub 项目 asciidoctor-chrome-extension。(是的，这个插件与 Chrome 的相同。)

Opera Asciidoctor.js Live Preview

现代文本编辑器

Asciidoctor 在大多数现代文本编辑器中都有体现，并且还有一个专门为其设计的编辑器。

AsciidocFX

AsciidocFX 是一个基于 Asciidoctor 的编辑器，提供了大量功能：跨平台（Windows、Mac、Linux），导出为 PDF、HTML、MOBI、EPUB 等。

项目的完整文档可在 http://asciidocfx.com/ 网站上找到。

AsciidocFX Editeur

Atom 包

Asciidoctor 社区提供了 2 个附加的 Atom 包：

AsciiDoc Preview 包

此包可激活对输入 AsciiDoc 的相应 HTML 的实时预览。它还提供 Asciidoctor 变量的自动完成功能。

AsciiDoc 包

此包启用 AsciiDoc 语言支持，特别是语法高亮。

Atom Editeur

Brackets 扩展

Adobe Brackets 编辑器的 AsciiDoc Preview 扩展除了实时 HTML 预览外，还提供了有趣的功能，例如将当前位置在 AsciiDoc 源文件中的位置与相应的 HTML 部分同步。此扩展支持数学表达式以及 PlantUml、Ditaa 和 Graphviz 图表。

更多信息

asciidoctor bracket extension demo

IntelliJ

对于 Java 开发者来说，IntelliJ (IDEA 及系列) 的 AsciiDoc 插件允许他们在同一个环境中编写代码和相关的文档。

更多信息请参考 GitHub 项目 asciidoctor-intellij-plugin。

asciidoctor intellij plugin demo

安装 Asciidoctor

从 gem 开始

$ gem install asciidoctor
$ gem install asciidoctor-diagram
$ gem install asciidoctor-pdf --pre
$ gem install asciidoctor-epub3 --pre

您可以在 RubyGem 上找到所有 gem（官方或非官方）。

从容器开始

$ docker pull asciidoctor/docker-asciidoctor (1)
$ docker run -v $(pwd)):/documents/ asciidoctor/docker-asciidoctor asciidoctor -D /documents *.adoc (2)
1 从 官方 Asciidoctor Docker 镜像 的 DockerHub 下载到本地。
2 在容器中使用 Asciidoctor 的示例。

更多关于 GitHub 项目 docker-asciidoctor 的信息。

构建环境

为了从持续集成系统生成文档，例如，Asciidoctor 为 Java 环境中的构建工具提供了插件。

Maven 插件

pom.xml
<plugins>
    <plugin>
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctor-maven-plugin</artifactId>
        <version>1.5.3</version> (1)
        ...
    </plugin>
</plugins>
1 插件版本与主要的 Ruby gem 版本相近。

更多关于使用 asciidoctor-maven-plugin 项目进行 Maven 配置的信息。

根据用例的配置示例可在 asciidoctor-maven-examples 项目中找到。

Gradle 插件

build.gradle
buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.3'
    }
}

apply plugin: 'org.asciidoctor.convert'

更多关于使用 asciidoctor-gradle-plugin 项目进行 Gradle 配置的信息。

根据用例的配置示例可在 asciidoctor-gradle-examples 项目中找到。

Ant 任务

build.xml
<project xmlns:asciidoctor="antlib:org.asciidoctor.ant">
...
    <target name="doc">
        <taskdef uri="antlib:org.asciidoctor.ant" resource="org/asciidoctor/ant/antlib.xml" classpath="lib/asciidoctor-ant.jar"/> (1)
        <asciidoctor:convert sourceDirectory="src/asciidoc" outputDirectory="target"/>
    </target>
...
</project>
1 “lib” 是包含 asciidoctor-ant.jar 的目录。

更多关于使用 asciidoctor-ant 项目进行 Ant 配置的信息。

Asciidoctor 的资金支持

作者： Dan Allen 和 Sarah White -

借助 Asciidoctor，我们致力于塑造写作和出版的未来，尤其是在技术文档领域。我们希望人们使用开源，不仅因为它是最好的软件，还因为它是有史以来文档化最好的软件。

我们已经走了很长一段路。我们对未来有更大的计划。为了将我们的愿景变为现实，Asciidoctor 项目需要资金。

更新： 我们已将 Asciidoctor 项目的资金平台从 BountySource 迁移到 OpenCollective。如果您希望为 Asciidoctor 项目提供财务支持，请访问 OpenCollective 上的 Asciidoctor。

为了确保 Asciidoctor 项目的持续成功和可持续性，我们在 Bountysource 的新资金平台上为 Asciidoctor 设立了 一个账户。（Bountysource 类似于开源项目的 Kickstarter）。您可以在 Asciidoctor 活动页面 上阅读有关此活动的更多详细信息，包括其运作方式和我们的初始目标。

Salt 平台将使我们能够接受来自组织和个人的财务支持，并将资金以我们认为最适合项目的方式分配。它还将使我们能够完全透明地说明项目的资金来源。最初的目標是讓我和 Sarah 能够全職投入 Asciidoctor 的開發。

Asciidoctor growth

在过去的三年里，Asciidoctor 已经取得了长足的增长和成熟。它现在是文档的关键组成部分，尤其是在开源领域。为了跟上项目的增长速度，管理整个 Asciidoctor 生态系统，并促进参与，我们需要投入更多的时间和精力来完成这项工作。我们还需要支付当前和未来的基础设施成本。这个活动筹集的资金越多（持续不断地），我们就能取得越大的成就，解锁越多的可能性，Asciidoctor 就能产生越大的影响。

通过获得资金，Asciidoctor 项目可以实质上雇佣我和 Sarah 来保持其平稳运行，并更频繁地发布组件。我们热爱运营 Asciidoctor 项目，我们也热爱这个社区。我们希望继续为社区服务，并做我们所热爱的事情，打造一个作家们一直想要的工具链。

让我们一起实现吧！

如果您有任何问题或疑虑，请随时回复。

  • 7 页中的 1