从 AsciiDoc 生成 DocBook

Asciidoctor 可以从 AsciiDoc 文档生成 DocBook 5 XML 输出格式。尽管 DocBook XML 不是一种可发布的格式，但它可以用于与处理 DocBook 的现有发布工具链集成。本页面将介绍如何使用 Asciidoctor 将 AsciiDoc 转换为 DocBook。

后端和转换器

Asciidoctor 内置的 DocBook 转换器已注册为 docbook 和 docbook5 后端。DocBook 转换器生成的 XML 符合 DocBook XML 模式。每个 AsciiDoc 元素都有一个对应的 DocBook 标签。

后端名称	`docbook`, `docbook5`
转换器类	`Asciidoctor::Converter::DocBook5Converter`
输出格式	XML
输出文件扩展名	.xml

生成 DocBook

要跟随下面的步骤操作，请使用您自己的 AsciiDoc 文件，或者将示例 1 的内容复制到一个新的纯文本文件中。

示例 1. my-document.adoc

= The Dangers of Wolpertingers
:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger

Don't worry about gumberoos or splintercats.
Something far more fearsome plagues the days, nights, and inbetweens.
Wolpertingers.

== Origins

Wolpertingers are {url-wolpertinger}[ravenous beasts].

请确保文件以 .adoc 文件扩展名保存。
要将 my-document.adoc 文档转换为 DocBook 5.0 格式，请使用后端标志设置为 docbook 的处理器进行调用。
```
$ asciidoctor -b docbook my-document.adoc
```

现在，当前目录中将出现一个名为 my-document.xml 的新 XML 文档。

$ ls
my-document.adoc  my-document.xml

这是 DocBook 转换器生成的 XML 片段。

示例 2. 从 AsciiDoc 生成的 XML

<?xml version="1.0" encoding="UTF-8"?>
<?asciidoc-toc?>
<?asciidoc-numbered?>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info>
<title>The Dangers of Wolpertingers</title>
<date>2020-12-08</date>
</info>
<simpara>Don&#8217;t worry about gumberoos or splintercats.
Something far more fearsome plagues the days, nights, and inbetweens.
Wolpertingers.</simpara>
<section xml:id="_origins">
<title>Origins</title>
<simpara>Wolpertingers are <link xl:href="https://en.wikipedia.org/wiki/Wolpertinger">ravenous beasts</link>.</simpara>
</section>
</article>

在 Linux 上，您可以使用 Yelp 查看 DocBook 文件。
```
$ yelp my-document.xml
```

DocBook 转换器生成的输出符合 DocBook 5.0 规范。

差异总结如下

在文档根目录使用 XSD 声明，而不是 DTD
使用 <info> 元素代替 <articleinfo> 和 <bookinfo> 作为文档信息
包含作者姓名的元素被包装在 <personname> 元素中
元素的 ID 使用 xml:id 属性定义
使用 <link> 代替 <ulink> 表示链接
链接的 URL 使用 xl:href 属性定义

如果您正在使用 Asciidoctor API，可以直接从您的应用程序生成 DocBook 文档。

示例 3. 从 API 生成 DocBook 输出

Asciidoctor.convert_file 'my-document.adoc', backend: 'docbook'

如果您需要输出 DocBook 4.5，您可能会发现社区支持的 DocBook 4.5 Converter 有用。

DocBook 转 PDF

尽管 Asciidoctor 项目提供了 Asciidoctor PDF 来执行直接的 AsciiDoc 到 PDF 的转换，您也可以选择通过 DocBook 进行转换为 PDF。DocBook 到 PDF 的转换由 DocBook 工具链处理。

DocBook 工具链的设置可能会带来挑战。本节提供了有关如何使用 DocBook 工具链的几点建议，但这并非详尽列表。如果您已经拥有一个可用的 DocBook 工具链，那么这些说明不适用于您。

xmlto

如果您使用的是 Linux 发行版，**xmlto** 包可能是一个选择。 xmlto 是一个简单的 shell 脚本，用于使用 DocBook 工具链将 XML 文件转换为各种格式。支持的格式包括作为输入格式的 DocBook 和作为输出格式的 PDF。

要安装 xmlto，请查找同名的软件包，并使用您的包管理器进行安装（例如，dnf install xmlto fop 或 apt-get install xmlto fop）。安装包后，您可以使用它通过 Apache FOP 从 DocBook 生成 PDF，如下所示：

$ xmlto --skip-validation --with-fop pdf doc.xml

如果您使用的是基于 RPM 的 Linux 发行版，您可以使用 dblatex 后端来生成 PDF。

$ xmlto --skip-validation pdf doc.xml

Asciidoctor 处理器添加了几个 XML 处理指令，以支持 DocBook 未提供的功能，例如主题分隔符和分页符。在使用 Apache FOP 后端时，您需要提供一个 XSL 样式表片段，该片段修改默认的 XSL 样式表以支持这些处理指令。您也可以将此样式表用作自定义 Apache FOP 生成的 PDF 的机会。

这是一个 XSL 样式表片段的示例，供您入门

示例 4. custom.xsl

<?xml version="1.0"?>
<xsl:stylesheet version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <xsl:param name="hyphenate">false</xsl:param>
  <xsl:param name="runinhead.default.title.end.punct"/>
  <xsl:param name="generate.toc">
    <xsl:choose>
      <xsl:when test="/processing-instruction('asciidoc-toc')">
article toc,title
book toc,title,figure,table,example,equation
      </xsl:when>
      <xsl:otherwise>
article nop
book nop
      </xsl:otherwise>
    </xsl:choose>
  </xsl:param>
  <xsl:param name="section.autolabel">
    <xsl:choose>
      <xsl:when test="/processing-instruction('asciidoc-numbered')">1</xsl:when>
      <xsl:otherwise>0</xsl:otherwise>
    </xsl:choose>
  </xsl:param>
  <xsl:template match="processing-instruction('asciidoc-br')">
    <fo:block/>
  </xsl:template>
  <xsl:template match="processing-instruction('asciidoc-hr')">
    <fo:block space-after="1em">
      <fo:leader leader-pattern="rule" rule-thickness="0.5pt" rule-style="solid" leader-length.minimum="100%"/>
    </fo:block>
  </xsl:template>
  <xsl:template match="processing-instruction('asciidoc-pagebreak')">
     <fo:block break-after='page'/>
  </xsl:template>
</xsl:stylesheet>

按如下方式将此样式表传递给 xmlto

$ xmlto --skip-validation --with-fop -m custom.xsl pdf doc.xml

要获得更多关于如何自定义样式表的想法，请参阅 fopub 项目中的 XSL 样式表。

fopub

与 xmlto 类似的替代方案是 fopub。fopub 使用 Java 和 Gradle 构建工具来包装 DocBook 工具链。使用 fopub 进行 DocBook 到 PDF 转换的唯一先决条件是 Java 开发工具包（JDK），它提供了 Java 运行时。

请注意，fopub 项目已归档。但是，它仍然可能有用。

要获取 fopub，您必须克隆存储库。克隆完成后，您可以在该存储库中运行 fopub 脚本来将 DocBook 文件转换为 PDF。

$ ./fopub README.xml

fopub 的优点在于它预先配置为使用 AsciiDoc 处理指令来转换 DocBook。它提供的样式表还优化了 DocBook 工具链提供的视觉样式的某些粗糙边缘。但是，该项目不再积极维护，因此在决定是否使用它时请牢记这一点。作为替代方案，您可以尝试 db-toolchain，它定位为 fopub 的后继者（尽管更复杂）。

Maven 插件

如果您正在使用 Maven 构建文档，那么您可能会考虑使用 docbkx 插件从 DocBook 生成 PDF。您可以在 Asciidoctor Maven 示例存储库中找到示例项目。

docbkx

使用这些插件的典型方式是从 Asciidoctor Maven plugin 开始的处理管道。Asciidoctor Maven 插件使用 Asciidoctor 来生成 DocBook 文件。