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

图片来源

Internet Archive Book Images。由 Opensource.com 修改。CC BY-SA 4.0

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

DocBook 是一种 XML 模式。XML 是一种可扩展标记语言，很像 HTML。它真正无处不在，但您可能通过 RSS 或 Atom、LibreOffice 和 Apache OpenOffice 的 Open Document 格式、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 时，由于查找/替换错误，telecommunication 这个词在其整个在线文档中都显示为 sparkmunication。该故障在其网站上持续了几天，然后才注意到并纠正了明显的错误。更好的正则表达式会有所帮助，但如果使用 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，有时需要 US 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。

标签

文档