docbook

最初发明计算机是为了进行数学运算，并且它们确实做得很好。 但是不久之后，用户就可以将其未来派计算器重新用于精美的动态打字机中。 现在，人类可读的文本驱动了计算，因此为您编写的文本选择正确的格式非常重要。

DocBook是XML模式。 XML是一种很像HTML的可扩展标记语言。 它确实无处不在，但是您可能通过RSS或Atom，LibreOffice和Apache OpenOffice的Open Document格式，Inkscape和SVG文件格式知道它，等等。 实际上，可以肯定地说，如果您拥有计算机或移动设备，则其中包含XML。

这是原始形式的样子：

DocBook本身易于学习且易于编写，它也是可用的最灵活的格式之一。 DocBook提供了其他格式，例如Markdown和reStructured Text。 DocBook不提供的内容可以通过通用XML来实现。

但是，为什么在存在更简单的替代方法时又要花时间学习DocBook？ 当您可以对原本纯文本加一些结构并最终获得高度可移植，计算机和人类可读的数据时，为什么还要打扰标记语言呢？

安顿下来。一切都会揭晓。

失败更快

使用更简单的格式与使用DocBook之间的明显区别是DocBook会在出现问题时告诉您。 许多其他格式（例如Markdown和HTML）都会静默失败。 通常感觉很好，因为结果是呈现了文档。 您按Enter键，您的文档将由转换所需的任何解析器或处理器处理，然后完成。 真是太好了。

但是，无声失败的现实是它仍然失败。 您可能已经得到输出，并且大多数看起来都很好，但是未捕获的错误呢？ 也许它渲染不正确，但是如果它被埋在200页文档的第42页中，您何时会注意到？ 错误可能在文档的Web版本中正确显示，但对于打印版本却错误显示。

像所有XML一样，DocBook非常严格。 例如，如果在关闭<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中学习新东西的逻辑流程往往很简单：

1. 转到DocBook网站。
2. 在主列表中找到合适的标签。
3. 请参阅标签的文档，以了解如何正确使用它。

这里的所有都是它的。 它与学习HTML大致相同：在最初的几分钟内学习基础知识，并随时提供参考资料以根据需要学习更多信息。

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

语义学

最后，DocBook很重要，因为它提供有关您的数据的数据。 DocBook标签并不是要指示内容的样式，而是要对要传达的信息进行分类。 像HTML和CSS一样，样式DocBook稍后出现，并且完全具有延展性。 DocBook标签为您的单词提供语义含义。

语义学现在对您似乎并不那么重要，但是以下是两个很好的例子，说明元数据在现实世界中变得非常重要：

• 在没有移动电话存在之前，互联网上没有人会想到电话号码将需要<tel>标签。 如果有的话，肯定可以使用<em>或<strong>标记。 然后发生了移动电话，世界各地的人们都在使用用于拨打电话的同一设备上浏览互联网，这给您带来了极大的不便，那就是无法查找公司的电话号码并单击以进行拨打。电话。
• 新西兰的一家大型电话公司多年来一直被称为电信公司。 当将其更名为Spark时，由于查找/替换错误，在整个整个在线文档中电信一词都显示为火花 。 该故障在其网站上已经存在了好几天，然后才注意到并纠正了明显的错误。 更好的正则表达式会有所帮助，但使用DocBook实体或<trademark>标签根本不会发生。

随着技术的发展，对您编写的信息进行分类现在非常重要。

轻松创建第一个DocBook文档

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

1. 打开一个文本编辑器。 只要可以保存纯文本文件，请使用您最喜欢的任何文本编辑器。 所有的好人都做： Gedit ， Geany ， Kate ， Nano ， Jove ， Emacs ， Atom等等。
2. 打开Web浏览器以访问DocBook 5.2：权威指南以供参考。
3. 在您的Web浏览器中打开另一个选项卡，以找到article元素引用，然后滚动到页面底部。 复制示例框中的文本并将其粘贴到文本编辑器中。
4. 使用示例文本作为模板并编写一些内容。 该示例的某些标头比您可能需要的更为冗长，因此在此我删除了一些多余的标头。
   < 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>元素指定一个或多个与标题相关的元素是必需的，但所有其他标签都是可选的。

5. 完成编写后，就该呈现文档了。 有几种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中编写的内容越多，您所学的标签和属性就越多，最终您可能会发现很难回到一种不太明确的格式。

具有样式的高级DocBook

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

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

它很专业，但是很痛苦。 尽管如此，它还是可以应用其他样式的重要基础。

HTML和EPUB输出

如果目标包含HTML，则可以继续使用Pandoc，指示它使用自定义CSS。

最终的结果是动态，轻巧，现代，并且魅力十足。

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文件， Apache FOP是将格式化对象转换为PDF的Java应用程序。

在开始使用DocBook样式时，可以轻松进行修改，这是您的字体选择。 字体易于更改，并在最终产品中产生显着差异。

1. 添加到默认样式的第一步是编辑外部样式表。 为了检测字体，然后创建一个名为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 >

   这会将所有TTF字体注册在您的个人或系统字体目录中。 您不必将其指向标准字体目录，但它必须是绝对路径，而不是相对路径。

2. 修改样式的下一步是设置新样式选项，以使处理器知道它是什么。 有两种方法可以更改XSL参数。 您可以在xsltproc命令中动态设置参数，也可以在其他样式表中进行更改。

   我使用这两种方法，具体取决于更改的严重性。 对于我经常更改的简单样式（例如页面大小（有时需要A4，有时需要US Letter），字体等），我将参数作为命令的一部分传递。 这样，我可以快速，轻松地并且独立于自定义样式表来更改它们。 设置字体：

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

   可在DocBook XSL样式表用户参考：参数中找到有效参数的列表。

3. 要输出为PDF，请告诉FOP在fonts.xml文件中注册字体：
   $ fop -c fonts.xml tmp.fo myDocbook.pdf

XSL样式表

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

这是一个简单的例子。

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

该过程类似于样式字体。

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

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

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

这将在样式表中为与注释匹配的所有元素创建一个模板。 每当XSL处理器找到<note>标记时，它就会放到XSL-FO块中，以描述如何打印元素（无论纸张是数字的还是物理的）。

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

获取输出：

语法没有CSS语法那么简洁或简单。 但是，简单样式遵循相同的格式：

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

像CSS一样，了解所有选项都需要花费时间和实践，但是一旦掌握了要点，就很简单。 更复杂的XML通过依赖项，变量，条件等为您提供更复杂的规则。 有关详尽的概述，请参见权威的DocBook XSL：完整指南网站。

使用DocBook

DocBook是为技术作家发明的，其许多标签都体现了这一点。 但是，无论是技术写作，小说还是RPG设计 ，我都会使用DocBook，这是一个功能强大，具有行业实力的系统。

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

我还使用Markdown作为中间格式。 我通常在DocBook中写Opensource.com文章，然后输出到Markdown，以便站点编辑器可以轻松地查看和转换我的工作。 如果您正在运行自己的网站，则可以直接从DocBook转换为HTML，这非常有用，并且可以控制使用哪些标记，类和ID，但是当您暂时想忽略源元数据并仅提供源代码时，Markdown是一个很好的中间步骤。文字。

对于其他所有内容，DocBook是一个很好的解决方案。 尝试一下，您将永远不会再以相同的方式看待文字处理器，文本或XML。

翻译自: https://opensource.com/article/17/9/docbook

docbook