从 AsciiDoc.py 迁移

AsciiDoc.py 是原始的、遗留的基于 Python 的 AsciiDoc 语言处理器。它已被 Asciidoctor 取代。如果您目前使用 AsciiDoc.py 来转换您的 AsciiDoc 文档并准备切换到 Asciidoctor，您需要将您的旧版 AsciiDoc 内容迁移到 Asciidoctor 定义和支持的官方 AsciiDoc 语法。这样做，您还将受益于自 Asciidoctor 接管语言开发以来添加到 AsciiDoc 语言的增强功能。本页涵盖了这些差异以及如何迁移。

本文档专门介绍从 AsciiDoc.py 8.6 迁移。

处理器调用

Asciidoctor 处理器是 AsciiDoc.py 的直接替代品。您可以将对 AsciiDoc.py (asciidoc) 的调用替换为对 Asciidoctor (asciidoctor) 的等效调用。

$ asciidoctor document.adoc

如果您的文档大量使用了 AsciiDoc.py 支持的旧版 AsciiDoc 语法，则启用兼容模式可能会有更好的效果

$ asciidoctor -a compat-mode document.adoc

但是，兼容模式严格来说只是一个迁移辅助工具。您应该只将其作为迁移内容的临时措施。它不是您想长期依赖的东西，并且被认为是已弃用的。

默认 HTML 后端

AsciiDoc.py 使用 XHTML 1.1 作为其默认输出。Asciidoctor 的默认输出是 HTML 5 (即 backend=html5)，而 html 后端映射到 html5。

主题

AsciiDoc.py 提供了一个封装 CSS、JavaScript 和图片的themizing 机制。--theme 选项激活其中一个主题，该主题从您的主目录解析。在 Asciidoctor 中，您使用 CSS 样式表来控制主题，您可以使用 -a stylesheet=<stylesheet> 来指定。

如果您需要更高级的主题，您可以通过 docinfo 文件或 后处理器扩展注入其他资源。

默认 HTML 样式表

Asciidoctor 和 AsciiDoc.py 的样式表看起来非常不同，但它们大多是可互换的，因为两个处理器的底层 HTML 结构几乎相同。

如果您更喜欢 AsciiDoc.py 的样式表，您可以通过将其从 AsciiDoc.py 的 stylesheets 目录复制，并指示 Asciidoctor 使用以下命令应用它：

$ asciidoctor -a stylesheet=asciidoc.css document.adoc

请记住，Asciidoctor 中的默认样式表仅仅是默认的。如果您不喜欢它的外观，您可以自定义它。

与 AsciiDoc.py 不同，Asciidoctor 从 CDN 加载一些资源。Asciidoctor 可以配置为从本地文件加载所有资源。例如，您可以取消设置 webfonts 属性，这样生成的 HTML 就不会使用 Google Fonts 的字体。有类似的属性来控制其他资源的解析方式。

更新和弃用的 AsciiDoc 语法

作为 AsciiDoc 语言的管理者，Asciidoctor 重构了 AsciiDoc.py 最初引入的一些 AsciiDoc 语法，以使其更一致、更容易学习，并且在某些情况下更简洁。本节概述了对现代 AsciiDoc 语法的这些改进以及它与 AsciiDoc.py 识别的旧版 AsciiDoc 的区别。

如果以下表格中没有提到某个功能或属性，那么它在 Asciidoctor 中的工作方式与在 AsciiDoc.py 中一样。

内联格式

Feature AsciiDoc.py Asciidoctor 注释

斜体文本

'斜体文本' 或 _斜体文本_

_斜体文本_

参见 斜体。
启用 compat-mode 时会恢复到 AsciiDoc.py 语法。

等宽文本

+等宽文本+

`等宽文本` 或 [x-]+等宽文本+

参见 等宽。
启用 compat-mode 时会恢复到 AsciiDoc.py 语法。

字面等宽文本

`字面等宽文本`

`+字面等宽文本+` 或 [x-]`字面等宽文本`

参见 字面等宽。
启用 compat-mode 时会恢复到 AsciiDoc.py 语法。

弯引号“双引号”

``双引号''

"`双引号`"

参见 引号和撇号。
启用 compat-mode 时会恢复到 AsciiDoc.py 语法。

弯引号‘单引号’

`单引号'

'`单引号`'

参见 引号和撇号。
启用 compat-mode 时会恢复到 AsciiDoc.py 语法。

内联角色(s)

[role]#文本# 或 [role1 role2]#文本#

[.role]#文本# 或 [.role1.role2]#文本#

参见 文本跨度和内置角色。
虽然 Asciidoctor 仍识别内联角色的裸露、空格分隔的语法，但带有前导点的简写样式是首选。

字体大小角色

big, small

用户指定的角色 (例如，[.details]) 及其对应的 CSS 规则由样式表提供

参见 使用自定义内联样式。
Asciidoctor 中的默认样式表仍然为这些内置角色提供 CSS，但它们被认为是已弃用的。

颜色角色

aqua, aqua-background, 等

用户指定的角色 [.brand-primary] 及其对应的 CSS 规则由样式表提供

参见 使用自定义内联样式。
Asciidoctor 中的默认样式表仍然为这些内置角色提供 CSS，但它们被认为是已弃用的。

目录

Feature AsciiDoc.py Asciidoctor 注释

可滚动、左边距的目录

toc2

:toc: left

参见 定位目录。

TOC 位置

toc-placement 和 toc-position

:toc: <value>

参见 定位目录。

用户指定的目录位置

:toc-placement: manual

:toc: macro

参见 定位目录。

文档和章节标题

Feature AsciiDoc.py Asciidoctor 注释

两行式 (setext) 文档标题

标题
=====

= 标题

参见 文档标题。
当 Asciidoctor 检测到两行式文档标题时，它会通过隐式设置 compat-mode 来切换到兼容模式。要恢复此行为，请显式取消设置 compat-mode。

带下划线的章节标题

下划线长度必须与标题长度 +/- 2 个字符匹配。

== 1 级标题
=== 2 级标题
==== 3 级标题
===== 4 级标题

参见 章节标题和级别。

章节编号

numbered

sectnums

参见 章节编号。

Asciidoctor 在从章节标题自动派生 ID 时更加谨慎，以避免生成晦涩的 ID。

  • Asciidoctor 会删除任何开始和结束的 HTML/XML 标签，而 AsciiDoc.py 不会。

  • Asciidoctor 会删除任何字符引用 (例如，&copy;)，而 AsciiDoc.py 不会 (参见下一条规则)。

  • Asciidoctor 会删除任何无效字符 (例如，$)，而 AsciiDoc.py 会用 idseparator 属性的值替换这些字符。

  • Asciidoctor 会为离散标题自动生成 ID，而 AsciiDoc.py 不会。

为了确保您的 ID 具有最大的可移植性，最好在章节标题包含特殊字符或格式时显式定义它们。

表格

Feature AsciiDoc.py Asciidoctor 注释

表单元格

a| 或 asciidoc|

仅 a|

参见 向表中添加单元格和行。

表单元格分隔符

Python 正则表达式。

一个或多个字面字符或 \t 表示制表符。

参见 向表中添加单元格和行、表数据格式和 自定义分隔符。

表格单元格的水平和垂直对齐

halign, valign

列和单元格说明符

参见 按列对齐内容 和 按单元格对齐内容。

在 DocBook 中使表占据整页宽度

options="pgwide"

未实现

块

Feature AsciiDoc.py Asciidoctor 注释

块分隔符

分隔符行不必匹配长度。

开始和结束分隔符行的长度必须完全匹配。

参见 分隔块。

直通块的默认替换

将属性和宏替换应用于直通块

不将任何替换应用于直通块

在块上方添加 [subs="attributes,macros"] 以恢复行为。

替换

Feature AsciiDoc.py Asciidoctor 注释

替换 +

replacements2

post_replacements

参见 后替换。

在导入大块纯文本时，抑制内联替换并保留块缩进

plaintext

未实现

类似的等效项是 直通块 或带有 indent 属性的列表块。

数学表达式

AsciiDoc.py 和 Asciidoctor 可以转换嵌入的 LaTeX 和 AsciiMath 表达式 (例如，asciimath:[expression], latexmath:[expression] 等)。在 Asciidoctor 中，首先使用 stem 属性激活 STEM 支持。

杂项

Feature AsciiDoc.py Asciidoctor 注释

ifeval::[ ]

评估任何 Python 表达式。

评估简单的逻辑表达式，测试属性的值。

参见 ifeval 指令。

提供当前文档的名称

infile

未实现

提供当前文档的目录

indir

未实现

对命名文本应用特殊格式

specialwords

未实现

将所有文本中的制表符替换为空格，默认制表符大小为 8

tabsize (文档内和 include 指令)

仅文档内

Asciidoctor 仅在字面块中替换制表符为空格，并且该属性没有默认值。换句话说，除非在块或文档上设置了此属性，否则在字面内容块中不会展开制表符。对于所有其他文本，Asciidoctor 的制表符通过 CSS 固定为 4 个空格。参见 规范化块缩进。

docinfo 属性

docinfo 属性值已通过 Asciidoctor 1.5.5 引入到 AsciiDoc 中，以取代不那么具有描述性的 docinfo1 和 docinfo2 属性。以下是使用新值的旧属性的等效项

  • :docinfo: = :docinfo: private

  • :docinfo1: = :docinfo: shared

  • :docinfo2: = :docinfo: shared,private

showcomments

在 AsciiDoc.py 中，单行注释可以使用 showcomments 转换为 DocBook <remark> 元素。此功能在 Asciidoctor 中未实现，但您可以使用扩展、ifdef 指令或直通块（如下例所示）将注释发送到输出。

ifdef::showcomments+basebackend-docbook[]
++++
<remark>Your comment here</remark>
++++
endif::[]

兼容模式

我们希望继续发展和完善 AsciiDoc 语法，但我们也认识到兼容性非常重要。这就是为什么 Asciidoctor 提供与 AsciiDoc.py 的兼容模式 (又名 compat mode) (以及一些内联过渡语法)。

Compat mode 将帮助您保持或从 AsciiDoc.py 识别的旧版 AsciiDoc 语法迁移到 Asciidoctor 识别的现代 AsciiDoc 语法。此模式仅应作为迁移的辅助工具，而不是长期策略。

如果您现在无法迁移，可以通过在文档头中设置 compat-mode 文档属性或将其传递给处理器来激活兼容模式

$ asciidoctor -a compat-mode document.adoc

您还可以通过以 setext 样式 (即两行式) 文档标题开始文档来隐式启用兼容模式

Compat Mode
===========

ifdef::compat-mode[Compat mode is on!]

如果您更喜欢 setext 样式的文档标题，但又不想启用兼容模式，您必须显式取消设置 compat-mode 属性。

Not Compat Mode
===============
:!compat-mode:

ifndef::compat-mode[Compat mode is not on.]

启用兼容模式后，Asciidoctor 会调整其部分行为和对 AsciiDoc 的解释，以更紧密地匹配 AsciiDoc.py。最显著的区别是，反引号现在仅表示等宽文本，而不是字面等宽文本。字面等宽文本使用复合标记表示，该标记结合了内联直通和等宽格式。

Feature 源码 结果

等宽字体

`1...10`

1…​10

字面等宽

`+1...10+`

1...10

斜体

'文本'

文本

要了解有关兼容模式激活的适应性的更多信息，请参阅 内联格式。

如果您编写的内容是为了用 AsciiDoc.py 处理，并且您还没有准备好迁移，或者需要逐步迁移，Asciidoctor 的兼容模式将有助于确保您现有的内容能够继续工作 (在可能的情况下)。

配置文件

Asciidoctor 不使用 .conf 文件或过滤器，因此 --conf-file、--dump-conf 和 --filter 不适用。取而代之的是，Asciidoctor 提供了一个 扩展 API，它取代了 AsciiDoc.py 中基于配置的扩展和过滤器机制。

本地化

AsciiDoc.py 包含内置的 .conf 文件，用于翻译内置标签。在 Asciidoctor 中，您必须显式定义这些标签的翻译。有关详细信息，请参见 本地化支持。

AsciiDoc.py 扩展

Asciidoctor 中的扩展机制完全不同，但大多数标准扩展都已重新实现，因此它们应该可以正常工作，只需进行少量更改。

AsciiDoc.py Asciidoctor

source

  • 您可以选择多种 源代码高亮器。

  • 源代码高亮器值是内置的。

  • src_numbered、src_tab、args 未直接实现，但请检查您正在使用的语言高亮器及其功能和配置方法。

music

未实现。

[latex] 块宏

使用 stem 块。

graphviz

使用 Asciidoctor Diagram。

自定义扩展

AsciiDoc.py 自定义扩展是 Python 命令，因此它们不能与 Asciidoctor 一起使用。根据您选择的 Asciidoctor 处理器，您可以用 Ruby、Java 或 JavaScript 重写您的扩展。

提取文本

AsciiDoc.py 提供了一个名为 a2x.py 的 DocBook 工具链的前端。该脚本可以从 AsciiDoc 文档生成各种输出格式。其中一种格式是文本 (又称“纯文本”)。为了提取文本，DocBook 工具链首先将 AsciiDoc 转换为 HTML，然后使用 lynx 从该文档中提取文本。

在 Asciidoctor 中，有多种提取 AsciiDoc 文本的方法。一种方法是编写一个映射到 text 后端的 Asciidoctor 转换器，该转换器 将 AsciiDoc 转换为纯文本。另一种方法是将 AsciiDoc 转换为 HTML，然后使用文本浏览器从 HTML 输出文档中提取文本，就像 DocBook 工具链所做的那样。

在继续之前，值得注意的是，“纯文本”没有普遍的定义。这完全取决于您试图提取哪些信息。这就是为什么 Asciidoctor 核心不提供文本后端的原因。让我们考虑一下可用的工具。

作为 lynx 的替代方案，文本浏览器 w3m 在从 HTML 文档提取文本方面做得很好。例如：

$ w3m -dump -cols 120 doc.html > doc.txt

您可以设置列数，以便不按固定行宽硬换行。此值的上限为 MAX_INT (2147483647)。您可以使用 Perl 动态检索该值。

$ w3m -dump -cols $(perl -MPOSIX -e 'print INT_MAX') doc.html > doc.txt

似乎无法配置 w3m 以保留指示标题的标记。但是，文本浏览器 elinks 默认通过缩进来提供此行为。

$ elinks -dump 1 -no-references -no-numbering -dump-width 50000 doc.html > doc.txt

另一个选择是 Node.js 的 html-to-text 模块，它可以解析 HTML 并返回漂亮的文本。

如果您想在 AsciiDoc 转换期间提取文本，您可以使用 Asciidoctor 后处理器扩展来完成。

require 'open3'

Asciidoctor::Extensions.register do
  postprocessor do
    process do |doc, output|
      outfile = (doc.attr 'outfile').sub %r/\.\S+$/, '.txt'
      Open3.popen2 'elinks -dump 1 -no-references -no-numbering' do |is, os|
        is.print output
        is.close
        File.write outfile, os.read
      end
      output
    end
  end
end

此扩展将在转换器写入的文档旁边写入一个扩展名为 .txt 的文件。

Doctest

AsciiDoc.py --doctest 运行其单元测试。请参阅 贡献指南以了解如何运行 Asciidoctor 单元测试。Asciidoctor 还有一个 doctest 工具，您可以在创建自定义 HTML 或 XML 转换器时使用。

帮助主题

在 AsciiDoc.py 和 Asciidoctor 中，--help CLI 选项默认显示命令用法。它还可以使用 --help syntax 显示语法备忘单，或使用 --help manpage 显示 man 页。

在 AsciiDoc.py 中，--help manpage 选项会发出 man 页的纯文本版本。另一方面，Asciidoctor 输出格式化的 man 页，以便您可以使用 man 分页器。要查看它，您需要像下面这样将结果通过管道传输到 man 命令

$ asciidoctor --help manpage | man /dev/stdin

或

$ asciidoctor --help manpage | man -l -

如果您想在 Asciidoctor 中查看纯文本版本，您可以像下面这样将输出通过 col 命令进行路由

$ asciidoctor --help manpage | man -l - | col -bx

或者，您可以在线查看 Asciidoctor 的 man 页，网址为 asciidoctor(1)。