DocBook 简介：一种值得学习的灵活标记语言

图片来源：

互联网档案馆图书图片。由 Opensource.com 修改。CC BY-SA 4.0

计算机最初是为了进行数学运算而发明的，而且它们在这方面做得非常出色。但是用户很快就将他们未来的计算器改造成了精美的动态打字机。现在，人类可读的文本驱动着计算，因此为编写的文本选择正确的格式非常重要。

DocBook 是一种 XML 模式。XML 是一种可扩展标记语言，很像 HTML。它真正无处不在，但您可能通过 RSS 或 Atom、LibreOffice 和 Apache OpenOffice 的开放文档格式、Inkscape 和 SVG 文件格式等等了解它。事实上，可以肯定地说，如果您拥有计算机或移动设备，那么上面就有 XML。

这就是它的原始形式

 <chapter>
<title>My title goes here</title>

<para>
 Paragraph text goes here.
</para>

<section>
 <title>A section title</title>

<para>
 More paragraph text. Some in <emphasis>italics</emphasis>.
</para>
</section>
</chapter>

DocBook 本身易于学习和编写，并且也是最灵活的格式之一。Markdown 和 reStructured Text 等其他格式所缺乏的，DocBook 提供了。而 DocBook 没有提供的，可以通过通用 XML 实现。

但是，在更简单的替代方案存在的时候，为什么要费心学习 DocBook 呢？当您可以为原本的纯文本施加一点结构，最终得到高度可移植、计算机和人类可读的数据时，为什么要费心使用标记语言呢？

请坐好。一切都将揭晓。

更快地失败

在更简单的格式和 DocBook 中工作的一个明显区别是，DocBook 会告诉您何时出错。许多其他格式（如 Markdown 和 HTML）会静默失败。通常，这感觉很好，因为结果是您的文档被呈现了。您按下Enter键，您的文档会被任何解析器或处理器处理以进行转换，您就完成了。多么美好的感觉。

在更简单的格式和 DocBook 中工作的一个明显区别是，DocBook 会告诉您何时出错。

然而，静默失败的现实是，它仍然失败了。您可能得到了输出，并且大部分看起来都很好，但是没有捕获到的错误呢？也许它错误地呈现了某些内容，但如果它埋在 200 页文档的第 42 页中，您什么时候会注意到？也许该错误在文档的网络版本中正确呈现，但在打印版本中却不正确。

DocBook，像所有 XML 一样，以严格著称。例如，如果您在关闭 <chapter> 后放置 <para>，那么您的文档构建将失败，并且通常会详细地失败。由于 DocBook 是 XML，您甚至可以运行您的源代码通过 xmllint 来尽早发现错误。

体验错误绝非易事。看着您的作品在非法标签和语法错误中逐渐消失，而不是构建成精美的 EPUB、网页或 PDF，这并不有趣。为了避免这种失望，大多数处理器接受一个临时忽略错误的选项，例如 --skip-validation，但最终失败很重要。失败会识别您源文件中的缺陷，并保护您免受产品中不愉快的意外。

比看起来更容易

DocBook 有时因难以学习而闻名。我发现，通常情况下，困难的不是 DocBook，而是人们围绕它构建的独特工具链，这些工具链具有陡峭的学习曲线。

与 HTML 相比，DocBook 的标签是自描述的。您想写一篇文章还是一本书？分别以 <article> 或 <book> 标签开头。在书中开始新章节，或在文章中开始新节，分别使用 <chapter> 或 <section>。使用 <para> 开始段落，使用 <orderedlist> 开始有序列表，使用 <listitem> 输入列表项，依此类推。

与 Markdown 和 AsciiDoc 相比，DocBook 看起来很复杂，但如果您考虑结构化文本中所有不直观的规则，DocBook 的规则似乎并没有那么糟糕。

从原始 Markdown 规范中学习语法通常是一个反复试验的过程，然后进行一系列绝望的互联网搜索，这意味着要仔细研究所有不同的 Markdown 风格和解析器，以找到最适合正确答案的候选者。CommonMark，一个致力于定义更严格和更规范的规范的项目，有所帮助，但用户常常被学习基础知识的容易程度所迷惑，却发现要获得高级结果会带来令人惊讶的学习曲线。

幸运的是，Markdown 接受 HTML 作为回退标记选项，并且有很多工具和 Markdown 变体可以弥补原始规范的不足。即便如此，如果您要为多个不同的输出目标编写复杂文档，那么它可能并不像所有“在 15 分钟内学习 Markdown”风格的博客中看起来那么容易。

在 DocBook 中学习新事物的逻辑流程往往始终如一地简单

转到 DocBook 网站。
在主列表中找到合适的标签。
参考标签的文档，了解如何正确使用它。

这就是全部。它与学习 HTML 大致相同：在最初几分钟内学习基础知识，并随时备查参考资料以根据需要学习更多内容。

根据您对 XML 的了解程度，可能会有一些意外，但 DocBook 网站清楚地定义了每个标签的有效父子关系，并且每个标签的条目都提供了大量的示例。

语义

最后，DocBook 很重要，因为它提供了关于您数据的数据。DocBook 标签并非旨在支配您内容的样式，而是对您尝试传达的信息进行分类。与 HTML 和 CSS 类似，DocBook 的样式稍后出现，并且完全可塑。DocBook 标签为您的文字提供语义意义。

语义现在可能对您来说并不那么重要，但这里有两个很好的例子，说明了元数据在现实世界中变得真正重要的时刻

在移动电话出现之前，互联网上没有人会想到电话号码会需要 <tel> 标签。如果有什么的话，肯定 <em> 或 <strong> 标签就足够了。然后移动电话出现了，世界各地的人们都在他们用来打电话的同一设备上浏览互联网，无法查找公司的电话号码并点击它进行呼叫，这简直太不方便了。
新西兰一家主要的电话公司多年来一直被称为 Telecom。当它更名为 Spark 时，由于查找/替换错误，sparkmunication 这个词出现在其整个在线文档中，代替了 telecommunication。该故障在其网站上持续了几天，才被注意到并纠正了明显的错误。更好的正则表达式会有所帮助，但如果使用 DocBook 实体或 <trademark> 标签，这一切都不会发生。

对您编写的信息进行分类现在很重要，并且随着技术的发展，这一点将变得更加重要。

以简单的方式创建您的第一个 DocBook 文档

这里有一种快速简便的方法来开始使用 DocBook。此方法强调学习 DocBook 标签和语法，而不是构建复杂而灵活的工具链。

打开文本编辑器。使用您最熟悉的任何文本编辑器，只要它可以保存纯文本文件。所有好的编辑器都可以：Gedit、Geany、Kate、Nano、Jove、Emacs、Atom 以及许多其他编辑器。
打开一个 Web 浏览器，访问 DocBook 5.2：权威指南以供参考。
在 Web 浏览器中打开另一个标签页，访问 article 元素参考并滚动到页面底部。复制示例框中的文本并将其粘贴到您的文本编辑器中。

使用示例文本作为模板并编写一些内容。该示例的某些标题比您可能需要的更冗长，所以我在这里修剪掉了一些多余的内容。

<article xmlns='http://docbook.org/ns/docbook'>
 <info>
  <title>My first docbook document</title>
  <author><personname>
 <firstname>Seth</firstname>
 <surname>Kenlon</surname>
  </personname></author>
  <publisher><publishername>opensource.com</publishername></publisher>
  <pubdate>2017</pubdate>
 </info>

 <section id="intro">
  <title>Introduction</title>
  <para>Introductory text goes here.</para>
  </section>

 <section id="body">
  <title>Section with a title</title>
  <para>Main body text goes here.</para>
 </section>

 <section id="conclusion">
  <title>Conclusion</title>
  <para>Exciting and inspiring conclusion goes here.</para>
 </section>
</article>

如果您对标签是否是必需的存有疑问，只需参考标签的文档即可。概要部分会告诉您什么是必需的，什么是可选的。例如，<section> 元素指定需要一个或多个与标题相关的元素，但所有其他标签都是可选的。

完成编写后，就该呈现您的文档了。有几种 XML 处理器可用，但对于初学者来说最简单的是 Pandoc。它是那些“瑞士军刀”应用程序之一，可以将几乎任何类型的文本转换为几乎任何其他类型的文本。对于 DocBook 而言，它特别好的地方在于它默认具有吸引人的样式表，而大多数其他处理器呈现的输出非常通用，假设您打算应用自己的 XSL 样式表。
有各种各样的潜在目标，但命令基本上都是相同的
```
$ pandoc --from docbook --to epub3 --output myDocbook.epub myDocbook.xml

$ pandoc --from docbook --to markdown --output myDocbook.md myDocbook.xml

$ pandoc --from docbook --to html --output myDocbook.html myDocbook.xml

$ pandoc --from docbook --to latex --output myDocbook.pdf myDocbook.xml
```
这就是全部。您使用 DocBook 编写的内容越多，您学习的标签和属性就越多，最终您可能会发现很难回到不太明确的格式。

图片来源：

opensource.com

高级 DocBook，带样式

Pandoc 使 DocBook 像 HTML 一样简单，但 XML 很灵活，因此如果需要，您可以自定义构建 DocBook 文档的方式。

大多数处理器（Pandoc 除外）的默认 DocBook 渲染看起来有点像这样

图片来源：

opensource.com

它很专业，但非常朴素。尽管如此，它仍然是应用其他样式的重要基础。

HTML 和 EPUB 输出

如果您的目标涉及 HTML，您可以继续使用 Pandoc，指示它使用您的自定义 CSS。

$ pandoc --from docbook --to html \
--css=myStyle.css \
--output myDocbook.html myDocbook.xml

$ pandoc --from docbook --to epub3 \
--epub-stylesheet=myStyle.css --epub-cover-image=cover.jpg \
--epub-embed-font=fonts/foo.ttf --epub-embed-font=fonts/bar.ttf \
--output myDocbook.epub myDocbook.xml

最终结果是动态、轻量级、现代且与您制作的一样有吸引力。

PDF 和打印输出

渲染为 PDF 以进行数字分发或打印依赖于 LaTeX 或 XSL。我还没有学会 LaTeX，所以我选择了 XSL，但如果您是 LaTeX 用户，您可以将 Pandoc 与自定义模板一起使用。否则，这里简要介绍一下 XSL 和 xsltproc 命令。

XSL 是可扩展样式表语言，是 XML 世界的 CSS。如果您从 Linux 发行版或 DocBook 网站安装 DocBook，您将安装所有默认的 DocBook 样式表。当您使用 xsltproc 或 xmlto 等工具时，这些样式表将充当回退样式。

如果您不能（或选择不）安装 DocBook，您可以在 xsltproc 命令中手动指向样式表。

使用 xsltproc 构建 PDF 是一个两步过程。首先，您必须生成 .fo 文件，它是 XML 和 XSL 的组合，转换为 XSL-FO（格式化对象）标记。然后，您使用 Apache FOP 处理 .fo 文件，这是一个将格式化对象转换为 PDF 的 Java 应用程序。

$ xsltproc --output tmp.fo myDocbook.xml

$ fop tmp.fo myDocbook.pdf

在刚开始使用 DocBook 样式时，一个简单的修改是您的字体选择。字体很容易更改，并且会对您的最终产品产生显着的影响。

添加到默认样式的第一个步骤是编辑外部样式表。对于字体检测，然后创建一个名为 fonts.xml 的文件并输入此文本
```
<fop version="2.0">
 <renderers>
<renderer mime="application/pdf">
 <fonts>
  <directory recursive="true">/absolute/path/to/your/system/fonts</directory>
  <auto-detect/>
 </fonts>
</renderer>
 </renderers>
</fop>
```
这会注册您的个人或系统 fonts 目录中的所有 TTF 字体。您不必将其指向标准字体目录，但它必须是绝对路径，而不是相对路径。
修改样式的下一步是设置您的新样式选项，以便您的处理器知道它是什么。有两种方法可以更改 XSL 参数。您可以动态地将参数设置为 xsltproc 命令的一部分，或者您可以在附加的样式表中进行更改。
我使用这两种方法，具体取决于更改的严重程度。对于我经常更改的简单样式，如页面大小（有时我需要 A4，有时需要美式 Letter）、字体等，我将参数作为命令的一部分传递。这样，我可以快速、轻松且独立于我的自定义样式表更改它们。要设置字体
```
$ xsltproc --string-param body.font.family "League Gothic" \
--output tmp.fo \
myDocbook.xml
```
可以在 DocBook XSL 样式表用户参考：参数中找到有效参数列表。
要输出到 PDF，请告诉 FOP 使用您的 fonts.xml 文件注册您的字体
```
$ fop -c fonts.xml tmp.fo myDocbook.pdf
```

XSL 样式表

对于不太可能根据打印机要求、页面大小或心情更改的样式，我将规则放在自定义 XSL 模板中。XSL 模板可能非常复杂，因此随着时间的推移进行微小的调整和学习是一种很好的方法。

这是一个简单的例子。

在印刷书籍中常见的视觉提示是警告，例如注释、提示或警告，以背景颜色打印，以让读者知道它与当前叙述分开，但仍然对主题很重要。警告是 DocBook 中的不同元素，因此它们相对容易设置样式。

该过程与设置字体样式类似。

首先，在您的工作目录中创建一个名为 mystyle.xsl 的新文件。编辑它，使其包含此标题

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
 <xsl:import href="https://open-source.net.cn/usr/share/xml/docbook/xsl-stylesheets-1.78.1/fo/docbook.xsl"/>

xsl:import 行必须指向您系统上的样式表，无论您是已安装它，还是从主目录中的非标准位置使用它。

在同一文件中，输入一些样式规则

<xsl:template match="note">
 <xsl:variable name="id">
<xsl:call-template name="object.id"/>
 </xsl:variable>
 <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"
   space-before.minimum="0.8em"
   space-before.optimum="1em"
   space-before.maximum="1.2em"
   start-indent="0.25in"
   end-indent="0.25in"
   padding-top="6pt"
   padding-bottom="2pt"
   padding-left="4pt"
   padding-right="4pt"
   background-color="#ffffbd">
<xsl:if test="$admon.textlabel != 0 or title">
 <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"
   keep-with-next='always'
   xsl:use-attribute-sets="admonition.title.properties"
   font-family="League Script Thin"
   color="#348fdf"
   font-weight="bold">
<xsl:apply-templates select="." mode="object.title.markup"/>
 </fo:block>
</xsl:if>
            
<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"
   xsl:use-attribute-sets="admonition.properties"
   font-family="League Gothic">
  <xsl:apply-templates/>
</fo:block> 
 </fo:block>
 </xsl:template>
</xsl:stylesheet>

这会在您的样式表中为所有与 note 匹配的元素创建一个模板。每当 XSL 处理器找到 <note> 标签时，它都会插入 XSL-FO 块来描述元素的打印方式（无论是数字纸张还是物理纸张）。

使用 xsltproc 应用样式并输出到 PDF 到 FOP

$ xsltproc --string-param body.font.family "League Gothic" \
mystyle.xsl --output tmp.fo \
myDocbook.xml

$ fop -c fonts.xml tmp.fo myDocbook.pdf

获取输出

图片来源：

opensource.com

语法远不如 CSS 语法简洁或简单。但是，简单的样式遵循相同的格式

为您要影响的标签创建一个 <xsl:template> 块。
在 DocBook XSL 样式表用户参考中查找可用的 XSL 属性。
在 <fo:block> 中设置要应用的属性。

与 CSS 类似，了解所有选项需要时间和实践，但是一旦您掌握了它，它就很简单了。更复杂的 XML 会为您带来更复杂的规则，包括依赖项、变量、条件等等。有关详尽的概述，请参阅权威的 DocBook XSL：完整指南网站。

使用 DocBook

DocBook 是为技术作家发明的，它的许多标签都反映了这一点。但是，我将 DocBook 用于所有内容，无论是技术写作、小说还是 RPG 设计，它都是一个强大、工业强度的系统。

这并不意味着世界上没有 Markdown 或 org-mode 或其他文本格式的位置。如果我正在编写 README 文件或给自己写一个简短的注释，DocBook 就显得过分了，因为源文档也旨在成为最终的交付格式。换句话说，在历史上我曾经使用纯文本的地方，我现在使用 Markdown，因为 Markdown 的结构是对非结构化文本的巨大改进。

我也使用 Markdown 作为中间格式。我通常在 DocBook 中编写 Opensource.com 文章，然后输出为 Markdown，以便网站编辑可以轻松地审阅和转换我的作品。如果您运行自己的网站并且可以控制使用哪些标签、类和 ID，那么直接从 DocBook 到 HTML 非常棒，但当您暂时想忽略源元数据而只交付书面文字时，Markdown 可以作为一个出色的中间步骤。

对于其他一切，DocBook 都是一个很好的解决方案。试试看，您将永远不会以相同的方式看待文字处理器、文本或 XML。

标签

文档