docbook
最初发明计算机是为了进行数学运算，并且它们确实做得很好。 但是不久之后，用户就可以将其未来派计算器重新用于精美的动态打字机中。 现在，人类可读的文本驱动了计算，因此为您编写的文本选择正确的格式非常重要。
DocBook是XML模式。 XML是一种很像HTML的可扩展标记语言。 它确实无处不在，但是您可能通过RSS或Atom，LibreOffice和Apache OpenOffice的Open Document格式，Inkscape和SVG文件格式知道它，等等。 实际上，可以肯定地说，如果您拥有计算机或移动设备，则其中包含XML。
这是原始形式的样子：
< 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 >< chapter >
DocBook本身易于学习且易于编写，它也是可用的最灵活的格式之一。 DocBook提供了其他格式，例如Markdown和reStructured Text。 DocBook不提供的内容可以通过通用XML来实现。
但是，为什么在存在更简单的替代方法时又要花时间学习DocBook？ 当您可以对原本纯文本加一些结构并最终获得高度可移植，计算机和人类可读的数据时，为什么还要打扰标记语言呢？
安顿下来。一切都会揭晓。
失败更快
使用更简单的格式与使用DocBook之间的明显区别是DocBook会在出现问题时告诉您。 许多其他格式（例如Markdown和HTML）都会静默失败。 通常感觉很好，因为结果是呈现了文档。 您按Enter键，您的文档将由转换所需的任何解析器或处理器处理，然后完成。 真是太好了。
使用更简单的格式与使用DocBook之间的明显区别是DocBook会在出现问题时告诉您。 但是，无声失败的现实是它仍然失败。 您可能已经得到输出，并且大多数看起来都很好，但是未捕获的错误呢？ 也许它渲染不正确，但是如果它被埋在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中学习新东西的逻辑流程往往很简单：
转到DocBook网站。 在主列表中找到合适的标签。 请参阅标签的文档，以了解如何正确使用它。
这里的所有都是它的。 它与学习HTML大致相同：在最初的几分钟内学习基础知识，并随时提供参考资料以根据需要学习更多信息。
取决于您对XML的了解程度，可能会有一些意外，但是DocBook网站清楚地为每个标签定义了有效的父子关系，并且每个标签的每个条目都提供了大量示例。
语义学
最后，DocBook很重要，因为它提供有关您的数据的数据。 DocBook标签并不是要指示内容的样式，而是要对要传达的信息进行分类。 像HTML和CSS一样，样式DocBook稍后出现，并且完全具有延展性。 DocBook标签为您的单词提供语义含义。
语义学现在对您似乎并不那么重要，但是以下是两个很好的例子，说明元数据在现实世界中变得非常重要：
在没有移动电话存在之前，互联网上没有人会想到电话号码将需要<tel>标签。 如果有的话，肯定可以使用<em>或<strong>标记。 然后发生了移动电话，世界各地的人们都在使用用于拨打电话的同一设备上浏览互联网，这给您带来了极大的不便，那就是无法查找公司的电话号码并单击以进行拨打。电话。 新西兰的一家大型电话公司多年来一直被称为电信公司。 当将其更名为Spark时，由于查找/替换错误，在整个整个在线文档中电信一词都显示为火花。 该故障在其网站上已经存在了好几天，然后才注意到并纠正了明显的错误。 更好的正则表达式会有所帮助，但使用DocBook实体或<trademark>标签根本不会发生。
随着技术的发展，对您编写的信息进行分类现在非常重要。
轻松创建第一个DocBook文档
这是开始使用DocBook的快速简便的方法。 该方法强调学习DocBook标签和语法，而不是构建复杂而灵活的工具链。
打开一个文本编辑器。 只要可以保存纯文本文件，请使用您最喜欢的任何文本编辑器。 所有的好人都做： Gedit ， Geany ， Kate ， Nano ， Jove ， Emacs ， Atom等等。 打开Web浏览器以访问DocBook 5.2：权威指南以供参考。 在您的Web浏览器中打开另一个选项卡，以找到article元素引用，然后滚动到页面底部。 复制示例框中的文本并将其粘贴到文本编辑器中。 使用示例文本作为模板并编写一些内容。 该示例的某些标头比您可能需要的更为冗长，因此在此我删除了一些多余的标头。
< info > < title > My first docbook document </ title > < author >< personname > < firstname > Seth </ firstname > < surname > Kenlon </ surname > </ personname ></ author > < publisher >< publishername > </ publishername ></ publisher > < pubdate > </ 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 >< article xmlns = '/ns/docbook' >
如果您对是否需要标签有疑问，请参阅标签的文档。 内容提要部分告诉您什么是必需的，什么是可选的。 例如，<section>元素指定一个或多个与标题相关的元素是必需的，但所有其他标签都是可选的。
完成编写后，就该呈现文档了。 有几种XML处理器可用，但是对于初学者来说最简单的是Pandoc 。 它是那些“瑞士军刀”应用程序之一，可以将几乎所有类型的文本转换为几乎任何其他类型的文本。 对DocBook尤其有利的是，默认情况下它具有吸引人的样式表，而大多数其他处理器在假定您打算应用自己的XSL样式表的情况下呈现非常通用的输出。
潜在目标多种多样，但命令基本相同：
$ 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$ pandoc --from docbook --to epub3 --output myDocbook.epub myDocbook.xml
这就是全部。 您在DocBook中编写的内容越多，您所学的标签和属性就越多，最终您可能会发现很难回到一种不太明确的格式。
具有样式的高级DocBook
Pandoc使DocBook像HTML一样容易，但是XML是灵活的，因此，如果需要，您可以自定义构建DocBook文档的方式。
大多数处理器（除了Pandoc之外）的默认DocBook渲染看起来像这样：
它很专业，但是很痛苦。 尽管如此，它还是可以应用其他样式的重要基础。
HTML和EPUB输出
如果目标包含HTML，则可以继续使用Pandoc，指示它使用自定义CSS。
--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$ pandoc --from docbook --to html \
最终的结果是动态，轻巧，现代，并且魅力十足。
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应用程序。
$ fop tmp.fo myDocbook.pdf$ xsltproc --output tmp.fo myDocbook.xml
在开始使用DocBook样式时，可以轻松进行修改，这是您的字体选择。 字体易于更改，并在最终产品中产生显着差异。
添加到默认样式的第一步是编辑外部样式表。 为了检测字体，然后创建一个名为fonts.xml的文件并输入以下文本：
< renderers > < renderer mime = "application/pdf" > < fonts > < directory recursive = "true" >/ absolute / path / to / your / system / fonts </ directory > < auto-detect /> </ fonts > </ renderer > </ renderers > </ fop >< fop version = "2.0" >
这会将所有TTF字体注册在您的个人或系统字体目录中。 您不必将其指向标准字体目录，但它必须是绝对路径，而不是相对路径。
修改样式的下一步是设置新样式选项，以使处理器知道它是什么。 有两种方法可以更改XSL参数。 您可以在xsltproc命令中动态设置参数，也可以在其他样式表中进行更改。
我使用这两种方法，具体取决于更改的严重性。 对于我经常更改的简单样式（例如页面大小（有时需要A4，有时需要US Letter），字体等），我将参数作为命令的一部分传递。 这样，我可以快速，轻松地并且独立于自定义样式表来更改它们。 设置字体：
--output tmp.fo \ myDocbook.xml$ xsltproc --string-param body.font.family "League Gothic" \
可在DocBook XSL样式表用户参考：参数中找到有效参数的列表。
要输出为PDF，请告诉FOP在fonts.xml文件中注册字体：
$ fop -c fonts.xml tmp.fo myDocbook.pdf
XSL样式表
对于不太可能根据打印机要求，页面大小或心情而改变的样式，我将规则放在自定义XSL模板中。 XSL模板可能会变得非常复杂，因此进行细微调整和逐步学习是一种很好的方法。
这是一个简单的例子。
印刷书籍中常见的视觉提示是一种警告，例如注释，提示或警告，印刷在背景颜色上，以使读者知道它与当前的叙述是分开的，但对主题仍然很重要。 警示是DocBook中的不同元素，因此样式相对简单。
该过程类似于样式字体。
首先，在您的工作目录中创建一个名为mystyle.xsl的新文件。 编辑它，使其包含以下标题：
< xsl:stylesheet xmlns: xsl = "/1999/XSL/Transform" version = "1.0" > < xsl:import href = "/usr/share/xml/docbook/xsl-stylesheets-1.78.1/fo/docbook.xsl" />< ?xml version = '1.0' ? >
xsl：import行必须指向系统上的样式表，无论您已安装样式表还是从主目录中的非标准位置使用它。
在同一文件中，输入一些样式规则：
< xsl:variable name = "id" > < xsl:call-template name = "object.id" /> </ xsl:variable > < fo:block xmlns: fo = "/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 = "/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 = "/1999/XSL/Format" xsl:use-attribute-sets= "admonition.properties" font-family= "League Gothic" > < xsl:apply-templates /> </ fo:block > </ fo:block > </ xsl:template > </ xsl:stylesheet >< xsl:template match = "note" >
这将在样式表中为与注释匹配的所有元素创建一个模板。 每当XSL处理器找到<note>标记时，它就会放到XSL-FO块中，以描述如何打印元素（无论纸张是数字的还是物理的）。
使用xsltproc应用样式并将其输出到PDF到FOP：
mystyle.xsl --output tmp.fo \ myDocbook.xml $ fop -c fonts.xml tmp.fo myDocbook.pdf$ xsltproc --string-param body.font.family "League Gothic" \
获取输出：
语法没有CSS语法那么简洁或简单。 但是，简单样式遵循相同的格式：
为要影响的标记创建一个<xsl：template>块。 在DocBook XSL样式表用户参考中查找可用的XSL属性。 在<fo：block>中设置要应用的属性。
像CSS一样，了解所有选项都需要花费时间和实践，但是一旦掌握了要点，就很简单。 更复杂的XML通过依赖项，变量，条件等为您提供更复杂的规则。 有关详尽的概述，请参见权威的DocBook XSL：完整指南网站。
使用DocBook
DocBook是为技术作家发明的，其许多标签都体现了这一点。 但是，无论是技术写作，小说还是RPG设计 ，我都会使用DocBook，这是一个功能强大，具有行业实力的系统。
这并不意味着Markdown或org-mode或其他文本格式在世界上没有地位。 如果我正在给自己写一个README文件或简短说明，则DocBook会显得过大，因为源文档也将是最终交付格式。 换句话说，在历史上我曾经使用纯文本的地方，我使用Markdown，因为Markdown的结构比非结构化文本有了很大的改进。
我还使用Markdown作为中间格式。 我通常在DocBook中写文章，然后输出到Markdown，以便站点编辑器可以轻松地查看和转换我的工作。 如果您正在运行自己的网站，则可以直接从DocBook转换为HTML，这非常有用，并且可以控制使用哪些标记，类和ID，但是当您暂时想忽略源元数据并仅提供源代码时，Markdown是一个很好的中间步骤。文字。
对于其他所有内容，DocBook是一个很好的解决方案。 尝试一下，您将永远不会再以相同的方式看待文字处理器，文本或XML。
翻译自: /article/17/9/docbook
docbook
