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

Note
 这份文档专门介绍了从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 和图片的主题机制。--theme 选项可以激活其中一个主题，这些主题可以通过您的家目录解析。在 Asciidoctor 中，你可以使用 CSS 样式表来控制主题，你可以使用 -a stylesheet=<stylesheet> 来指定样式表。

如果您需要更高级的主题设置，您可以使用docinfo文件或post处理器扩展注入额外的资源。

默认HTML样式表

Asciidoctor 和 AsciiDoc.py 的样式表看起来差异很大，但它们大部分是可以互换的，因为这两个处理器的底层HTML结构几乎是一致的。

如果您更喜欢AsciiDoc.py的样式表，您可以通过从AsciiDoc.py的[.path]_stylesheets_目录中复制它，并指导Asciidoctor使用以下方法应用它：

asciidoctor -a stylesheet=asciidoc.css document.adoc

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

Important
 与AsciiDoc.py不同，Asciidoctor会从CDN加载一些资源。可以将Asciidoctor配置为从本地文件加载所有资源。例如，你可以取消设置`webfonts`属性，以便生成的HTML不使用Google字体。还有类似的属性来控制如何解析其他资源。

已更新和已弃用的AsciiDoc语法。

作为AsciiDoc语言的管理者，Asciidoctor重新考虑了最初由AsciiDoc.py引入的一些AsciiDoc语法，以使其更一致、更易学，而且在某些情况下更简洁。本节概述了对现代AsciiDoc语法的改进以及它与AsciiDoc.py认可的传统AsciiDoc的不同之处。

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

内联格式化

Feature AsciiDoc.py Asciidoctor Notes

italic text

'italic text' or _italic text_

_italic text_

See asciidoc:text:italic.html.
Reverts to AsciiDoc.py syntax when compat-mode is enabled.

monospace text

+monospace text+

`monospace text` or [x-]+monospace text+

See asciidoc:text:monospace.html.
Reverts to AsciiDoc.py syntax when compat-mode is enabled.

literal monospace text

`literal monospace text`

`+literal monospace text+` or [x-]`literal monospace text`

See Literal monospace.
Reverts to AsciiDoc.py syntax when compat-mode is enabled.

Curved “double quotes”

``double quotes''

"`double quotes`"

See asciidoc:text:quotation-marks-and-apostrophes.html.
Reverts to AsciiDoc.py syntax when compat-mode is enabled.

Curved ‘single quotes’

`single quotes'

'`single quotes`'

See asciidoc:text:quotation-marks-and-apostrophes.html.
Reverts to AsciiDoc.py syntax when compat-mode is enabled.

Inline role(s)

[role]#text# or [role1 role2]#text#

[.role]#text# or [.role1.role2]#text#

See asciidoc:text:text-span-built-in-roles.html.
While Asciidoctor still recognizes the bare, space-separated syntax for inline roles, the shorthand-style with the leading dot is preferred.

Font size roles

big, small

user-specified role (e.g., [.details]) with corresponding CSS rules provided by stylesheet

See asciidoc/text:custom-inline-styles.html.
The default stylesheet in Asciidoctor still provides CSS for these built-in roles, but they are considered deprecated.

Color roles

aqua, aqua-background, etc.

user-specified role [.brand-primary] with corresponding CSS rules provided by stylesheet

See asciidoc/text:custom-inline-styles.html.
The default stylesheet in Asciidoctor still provides CSS for these built-in roles, but they are considered deprecated.

目录

Feature AsciiDoc.py Asciidoctor Notes

Scrollable, left margin TOC

toc2

:toc: left

See asciidoc:toc:position.html.

TOC location

toc-placement and toc-position

:toc: <value>

See asciidoc:toc:position.html.

User-specified TOC location

:toc-placement: manual

:toc: macro

See asciidoc:toc:position.html.

文件和章节标题

特性 AsciiDoc.py Asciidoctor 注释

两行风格（setext）文档标题

Title
=====

= Title

参见asciidoc:document:title.html。+ 当Asciidoctor检测到两行风格的文档标题时，它会通过隐式设置`compat-mode`进入兼容模式。 要改变这一行为，需显式取消设置`compat-mode`。

下划线节标题

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

== 一级标题
=== 二级标题
==== 三级标题
===== 四级标题

参见asciidoc:sections:titles-and-levels.html。

节编号

numbered

sectnums

参见asciidoc:sections:numbers.html。

Asciidoctor在从节标题派生自动ID时更加小心，以避免生成晦涩难懂的ID。

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

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

  • Asciidoctor会移除任何无效字符（例如，$），而AsciiDoc.py则会用`idseparator`属性的值替换这些字符。

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

为了确保你的ID具有最大的可移植性，如果节标题包含特殊字符或格式化内容，最好显式定义它们。

桌子

特性 AsciiDoc.py Asciidoctor 注释

表格单元

a| 或 asciidoc|

仅 a|

参考 asciidoc:tables:add-cells-and-rows.html。

表格单元分隔符

一个Python正则表达式。

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

参考 asciidoc:tables:add-cells-and-rows.html、asciidoc:tables:data-format.html，及 自定义分隔符。

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

halign, valign

列和单元格指定符

参考 asciidoc:tables:align-by-column.html 和 asciidoc:tables:align-by-cell.html。

在DocBook中使表格全页宽度

options="pgwide"

未实现

积木

功能 AsciiDoc.py Asciidoctor 备注

块限定符

分隔线的长度不必完全匹配。

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

参见asciidoc:blocks:delimited.html。

passthrough块的默认替换

对passthrough块应用属性和宏替换

不对passthrough块应用任何替换

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

替换

特性 AsciiDoc.py Asciidoctor 备注

替换 +

replacements2

post_replacements

参见 asciidoc:subs:post-replacements.html。

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

plaintext

未实现

最接近的等价物是 穿透块或带有 缩进属性的列表块。

数学表达式

AsciiDoc.py 和 Asciidoctor 能够转换嵌入的 LaTeX 和 AsciiMath 表达式（例如，asciimath:[expression]，latexmath:[expression] 等）。在 Asciidoctor 中，首先通过使用 stem属性 来激活 STEM 支持。

杂项

功能 AsciiDoc.py Asciidoctor 备注

ifeval::[ ]

评估任何Python表达式。

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

参见 asciidoc:directives:ifeval.html。

提供当前文档的名称

infile

未实现

提供当前文档的目录

indir

未实现

对命名文本应用特殊格式

specialwords

未实现

使用默认的8个空格尺寸，将所有文本中的制表符替换为空格

tabsize（文档内和include指令中）

仅限文档内

Asciidoctor仅在verbatim块中将制表符替换为空格，且该属性没有默认值。 换言之，除非在块或文档上设置了该属性，否则verbatim内容块中的制表符不会扩展。 对于所有其他文本，Asciidoctor的制表符在CSS中固定为4个空格。 参见 规范块缩进。

文档信息属性

docinfo` 属性值是在 Asciidoctor 1.5.5 版本中引入 AsciiDoc 的，用以取代描述性不足的 docinfo1 和 docinfo2 属性。以下是使用新值替换旧属性的等价物：

  • :docinfo:` = `:docinfo: private

  • :docinfo1:` = `:docinfo: shared

  • :docinfo2:` = `:docinfo: shared,private

显示评论

在AsciiDoc.py中，可以通过`showcomments`将单行注释转化为DocBook中的`<remark>`元素。这个功能在Asciidoctor中尚未实现，但您可以使用扩展或ifdef指令和passthrough块将注释发送到输出，如下面的示例所示。

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

兼容模式

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

兼容模式将帮助你坚持使用或从AsciiDoc.py识别的传统AsciiDoc语法过渡到Asciidoctor识别的现代AsciiDoc语法。这种模式只应作为协助迁移的工具使用，而不是作为长期策略。

如果你现在无法进行迁移，你可以通过在文档头部设置`compat-mode`文档属性或者传递给处理器来激活兼容模式：

$ asciidoctor -a compat-mode document.adoc

你也可以通过以 setext 风格（即两行）的文档标题开始文档来隐式启用兼容模式：

兼容模式
===========

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 保持一致。最明显的区别是，反引号现在只表示等宽字体文本，而不是字面上的等宽文本。字面上的等宽文本是通过一种复合标记来表示的，该标记结合了内联直通（passthrough）和等宽格式设置。

特性 来源 结果

等宽字体

`1...10`

1…​10

字面等宽字体

`+1...10+`

1...10

斜体

'text'

text

要了解由兼容模式激活的适应性调整，请参考内联格式化。

如果你编写的内容是为了用AsciiDoc.py处理，并且你还没有准备好迁移，或者需要缓慢过渡到迁移过程，Asciidoctor的兼容模式将帮助确保你现有的内容可以继续运作（在可能的范围内）。

配置文件

Asciidoctor不使用[.path]_.conf_文件或过滤器，因此`--conf-file`、--dump-conf`和--filter`不适用。相反，Asciidoctor提供了一个替代AsciiDoc.py中基于配置的扩展和过滤机制的扩展API。

本地化

AsciiDoc.py 内置了转换内置标签的[.path]_.conf_文件。在 Asciidoctor 中，您必须显式定义这些标签的翻译。有关详细信息，请参阅 ROOT:localization-support.html。

AsciiDoc.py 扩展

扩展机制在Asciidoctor中完全不同，但是大多数标准扩展都已经重新实现，因此它们应该只需小改动就可以工作。

AsciiDoc.py Asciidoctor

source

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

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

  • src_numbered`、src_tab、args 不是直接实现的，但是检查你正在使用的高亮显示器它具有哪些功能以及如何配置它们。

音乐

未实现。

[latex] 块宏

使用 stem block。

graphviz

使用 Asciidoctor 图表。

自定义扩展

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

提取文本

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

从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的https://www.npmjs.com/package/html-to-text[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 运行了它的单元测试。查阅 contributing guide 学习如何运行 Asciidoctor 单元测试。Asciidoctor 也有一个 {url-org}/asciidoctor-doctest[doctest tool^]，您可以在创建自定义的 HTML 或 XML 基础转换器时使用它。

帮助主题

在AsciiDoc.py和Asciidoctor中，--help CLI选项默认显示命令用法。它还可以使用 --help syntax 显示语法提示卡片，或者使用 --help manpage 显示手册页。

在AsciiDoc.py中，`--help manpage`选项可以输出一个纯文本版本的手册页。另一方面，Asciidoctor输出的是格式化后的手册页，因此你可以用它配合手册页查看器使用。要查看它，你需要将结果通过管道传输给`man`命令，如下所示：

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

或者

$ asciidoctor --help manpage | man -l -

如果你想要通过Asciidoctor查看纯文本版本，你可以按照如下方式通过`col`命令来输出：

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

你也可以在{url-project}/man/asciidoctor[asciidoctor(1)]在线查看Asciidoctor的手册页面。