下载地址：https://DocBook.org/xml/5.0/DocBook-5.0.zip

这个DTD其实也可以不用下载，这里面就是DocBook DTD。下载好解压缩以后，DocBook.dtd文件在dtd的目录里。

下载地址：https://sourceforge.net/projects/DocBook/files/DocBook-xsl/1.79.1/DocBook-xsl-1.79.1.tar.bz2/download

上面的链接给出的版本是DocBook-xsl-1.79.1的版本，截止这份文档完稿，DocBook-xsl已经发展到了版本1.79.2。并且，项目寄存地址已经从sourceforge.net迁移到了github.com。如果需要最新版本的DocBook-xsl，可以到github上去下载。地址是https://github.com/DocBook

下载地址：https://www.java.com/zh-CN/download/

这份文档中涉及到的程序基本上都是由java开发的，所以我们需要java。

下载地址：https://sourceforge.net/projects/saxon/files/saxon6/6.5.5/saxon6-5-5.zip/download

Saxon是一个基于java的XSLT处理器，因其严格遵守XSLT标准而受到很多人的欢迎。saxon的作用是将我们DocBook规范的文档，根据xsl样式表转换为我们需要的格式，比如html、fo^[2]（pdf格式需要fo）等。

saxon版本很多，截至这份文档完稿，它的最新版本是10。关于saxon的更多信息可以参考它的官方网站：http://saxon.sourceforge.net/。在DocBook-xsl的相关手册里， 对saxon6.5描述较多，所以我选择了这个比较稳定但似乎又年代久远的sanon6-5.5。

与saxon功能类似的，还有xsltproc和xalan可以使用。

下载地址：https://dlcdn.apache.org/xalan/xalan-j/binaries/xalan-j_2_7_2-bin.tar.gz

xalan与saxon的作用类似。xalan是apache软件基金会的一个项目。xalan与saxon可以二选一。

下载地址：https://archive.apache.org/dist/xmlgraphics/fop/binaries/fop-2.4-bin.tar.gz

fop是Apache软件基金会下的一个xml相关的项目，项目网站是：http://xmlgraphics.apache.org/fop/。fop的作用是将saxon生成的fo文件转换为pdf文件。截至这份文档完稿，它的最新版本是2.6。

fop在我们需要的这些组件和软件里面，迭代是比较频繁的，特性增加了很多，易用性也提高了不少。记得最早使用fop的时候，在使用一些字体时，还需要将字体ttf等文件生成一份xml文件才行，而现在已经完全不需要了，只需要将字体复制到指定的目录，然后在配置文件fop.xconf里声明一下就可以了。如果字体文件规范，甚至都不需要声明。这个部分会在后面的配置部分介绍。

用于处理一些xsl的模板文件，在样式模板相关章节会用到。安装方法是直接使用debian的安装命令就可以了：

apt-get install xsltproc

字体是个有点大的问题，放在后面章节介绍。在这里我们需要三款字体，我使用的SourceHan（思源）字体族。我在发现思源字体之前有很多字体方面的问题困扰我。直到我发现了思源字体，很多问题才一扫而空。思源字体的背后是一个世界级的制作团队。主要受到adobe和google的赞助。而且它是开源的。它的官方网站是https://source.typekit.com/ ，一共有三款字体需要下载：source-han-sans，source-han-serif和source-han-mono。

下载地址：https://github.com/adobe-fonts/

下载好之后，把三个压缩文件解压，选取下面的三个字体：

把这三个字体保存到docware中的fonts目录中。

这可能是DocBook文档中最常见的文档起点。也是我们用得最多，但也是输入次数很少的标签。“一本书”只需输入两次，一头一尾：<book> </book>。

book的子节点之一，“章”的根节点。与chapter节点同级的还有preface（序言）和appendix（附录）。

sect1是“小节”的根节点，“小节”一共有5个级别，一级套一级，1套2，2套3...... sect1、sect2、sect3、sect4和sect5。如果不喜欢这5个标签，也可以使用section标签递归嵌套。

para就是paragraph的缩写。应该是用得最多的标签了吧。

title是在文档中应用非常广泛的标签，不仅是book,chapter,sect*等，在后面还会用到的表格、插图等都可以有一个标题。

XML文档通常以XML声明开始，通常包含版本、编码格式等，例如：

<?xml version="1.0" encoding="utf-8"?>

版本和编码格式会告诉处理程序采用什么的方式来处理我们的xml文本。一般情况下，xml的处理程序默认version是1.0，encoding是uft-8或utf-16，在这种情况下，我们可以不用写xml文档声明。如果使用xml1.1格式或其他的编码格式那就必须声明。

无论什么版本和编码，建议保留完整的声明。这是一种良好的习惯。

docbook DTD是docbook xml的文档声明，这也不是必须的。但，历史的原因，几乎所有的docbook xml文件都包含了这个部分。docbook DTD部分可以清晰地告诉我们使用了哪个版本的DTD及文档的根元素是什么，这个声明紧随xml声明之后，如下的样子：

<?xml version='1.0' encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
                   "http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd">

上面的声明告诉我们，文档的根元素是book，使用了5.0版本的dtd。在某些程序处理xml文档时，需要验证相关标签是否存在或者是否符合规范，那这个docbook.dtd就会被读取。如果我们已经下载这个docbook.dtd到我们的电脑里，也可以用将它指向本的的文件，如下：

<?xml version='1.0' encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
                   "/usr/local/docware/docbook-5.0/dtd/docbook.dtd">

	提示
	上面的例子根元素是book，另外常用的两个标签是article和set。article是一篇文章，篇幅上比book要小。set是book的合集，篇幅上更大。

根元素紧跟在文档类型声明之后，和docbook DTD的声明类似，这个部分也是可选的。但有时候很多程序会调用这些信息，而且docbook从版本5以后直接使用了一些xlink里的一些特性，所以建议保留这些内容：

<?xml version='1.0' encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
                   "/usr/local/docware/docbook-5.0/dtd/docbook.dtd">
                   
<book xmlns:xlink='http://www.w3.org/1999/xlink' 
      xmlns="http://docbook.org/ns/docbook" 
      xml:lang="zh_cn" 
      version="5.0">  

这个部分是在前面我们描述的“头”部分完成的，在根元素之前，在DTD声明之后。定义好之后，在适当的位置引用他们，那么我们的firstbook.xmll真实的样子就诞生了，如下的样子：

  1 <?xml version="1.0" encoding="utf-8"?>
  2 <!DOCTYPE book [
  3     <!ENTITY info SYSTEM "info.xml">
  4     <!ENTITY preface SYSTEM "preface.xml">
  5      
  6     <!ENTITY chapter01_beginning SYSTEM "chapters/chapter01_beginning.xml">
  7     <!ENTITY chapter02_xml SYSTEM "chapters/chapter02_xml.xml">
  8     <!ENTITY chapter03_xsl SYSTEM "chapters/chapter03_xsl.xml">
  9     <!ENTITY chapter04_fonts SYSTEM "chapters/chapter04_fonts.xml">
 10     
 11     <!ENTITY colophon SYSTEM "chapters/colophon.xml">
 12 ]>
 13 
 14 <book xmlns:xlink='http://www.w3.org/1999/xlink' 
 15       xmlns="http://docbook.org/ns/docbook" 
 16       xml:lang="zh_cn" 
 17       version="5.0">
 18 
 19 <title>docbook简要参考⼿册</title>
 20 <subtitle>DocBook 5.0 and XSLT 1.0 Stylesheet</subtitle>
 21 &info;
 22 &preface;
 23 
 24 &chapter01_beginning;
 25 &chapter02_xml;
 26 &chapter03_xsl;
 27 &chapter04_fonts;
 28 
 29 &colophon;
 30 </book>

分割好以后就有点文档工程的味道了。接下来就是完成各个章节的撰写。章节的撰写相对firstbook.xml来讲就相对简单里，不需要那些定义和声明，只要按照标准的docbook规范来书写就可以了。在这里以第一章为例来说明，如下：

  1 <chapter><title>制作第一份docbook文档</title>
  2   <para>前面已经提到过，docbook主要分为SGML和XML两个版本，... ...</para>
  3   <para>docbook的入门是有一定门槛的，... ...</para>
  4   <orderedlist>
  5     <listitem><emphasis>XML文档</emphasis>
  6       <para>首先，需要按照docbook DTD的规范要求，... ...</para>
  7     </listitem>
  8     <listitem><emphasis>XSL样式表</emphasis>
  9       <para>有了docbook格式的xml文件之后，... ...</para>
 10     </listitem>
 11     <listitem><emphasis>字体</emphasis>
 12       <para>有几种类型的字体需要我们提前准备好主要包括sans、serif、monospace等。后面会有详细的介绍。</para>
 13     </listitem>
 14     <listitem><emphasis>处理程序</emphasis>
 15       <para>有了docbook格式的文件、docbook-xsl样式表及字体，... ...</para>
 16     </listitem>
 17   </orderedlist> 
 18 </chapter>

其他的章节也是按照这样的方式来撰写。

这个文件里面包含了“书”的很多信息，主要是作者、版本信息、发行信息、出版日期等。

  1 <info>
  2 
  3   <corpauthor>****信息科技有限公司</corpauthor>
  4   <author><firstname>Li </firstname><surname>Lawrence</surname></author>
  5   <pubdate>2021年9月18日</pubdate>
  6 
  7   <copyright>
  8     <year>2021</year>
  9     <holder>ChunXin Li</holder>       
 10   </copyright>
 11 
 12   <legalnotice><title>legalnotice </title>
 13     <para>... ...</para>
 14   </legalnotice>
 15 
 16   <revhistory>
 17      <revision>
 18         <revnumber>1.0</revnumber>
 19         <date>2021年8月28日</date>
 20         <authorinitials>ddpt</authorinitials>
 21         <revremark>发布第二个Draft</revremark>
 22      </revision>
 23 
 24      <revision>
 25         <revnumber>1.0</revnumber>
 26         <date>2021年9月8日</date>
 27         <authorinitials>ddpt</authorinitials>
 28         <revremark>发布第一个Draft</revremark>
 29      </revision>
 30   </revhistory>
 31   
 32   <releaseinfo><para>This document was generated by chunxin.</para></releaseinfo>
 33   <abstract><title>摘要</title>
 34     <para>docware是基于docbook的一套文档发布工具... ...</para>
 35   </abstract>  
 36 </info>

这个例子里只是展示了一部分，关于书的信息（标签）还有很多，可以根据自己的需求添加或减少。

这两个文件是一本“书”的序言和后记。一般情况下也不是必须的。可以把喜欢的一些“引子”之类的东西写在序言里，把后续要做的或一些花絮写在后记里。

在book里，可以把preface和colophon标签看成和chapter是一样的，preface.xml大致如下的样子：

  1 <preface><title>写在前面</title>
  2   <para>在接触到docbook之前，写一些计算机技术相关的一些文档，对我来说是件很辛苦的事情。</para>
  3   <itemizedlist>
  4     <listitem>该用什么样的一些样式展示不同的一些文档元素？如一些代码、或者系统命令等。</listitem>
  5     <listitem>如何保证同样的文档元素总是保持一样的显示风格？</listitem>
  6     <listitem>如何进行版式的一些设计？用word来排版对我来说实在太痛苦。</listitem>
  7     <listitem>如何让文档能够同时生成在线阅读的版本和可以打印的版本？</listitem>
  8     <listitem>如何完成多人协作书写，又同时保证样式的完全一致？</listitem>
  9   </itemizedlist>
 10   <para>还有就是诸如如何进行版本控制等... ...</para>
 11 </preface>

colophon.xml大致如下的样子：

  1 <colophon><title>结束语</title>
  2  <para>... ...</para>
  3 </colophon>

  1 <xsl:param name="l10n.gentext.default.language">zh_cn</xsl:param>
  2 <xsl:param name="l10n.gentext.language">zh_cn</xsl:param>

这是对使用语言的设置，在样式表目录里有一个docbook-xsl-1.79.1/common/zh_cn.xml语言包文件，这是中文的语言包。这个文件里的内容都是预先设置好的固定文本。设置什么样的语言，处理程序就会找哪个语言包。docbook-xsl对中文的支持非常友好。

在样式表中主要有三类字体需要设置，如下所示：

  1 <xsl:param name="body.font.family">Source Han Serif CN,serif</xsl:param> 
  2 <xsl:param name="title.font.family">Source Han Sans CN,sans</xsl:param> 
  3 <xsl:param name="monospace.font.family">Source Han Mono SC,monospace</xsl:param> 

这三种字体分别描述如下：

设置正文的行高，这个可以根据自己的喜好设定。 1.7的意思是字体大小的1.7倍。

  1 <xsl:param name="line-height">1.7</xsl:param>

设定文档打印时版面的大小，有A0，A1，A3，A4... ....40几种尺寸可供选择。A4大概是平时用得最多的。

  1 <xsl:param name="paper.type">A4</xsl:param>

monospace.verbatim.properties是用于设置使用等宽字体文档元素的样式，例如前面提到的screen等。

  1 <xsl:attribute-set name="monospace.verbatim.properties"  
  2    use-attribute-sets="verbatim.properties monospace.properties">
  3   <xsl:attribute name="text-align">start</xsl:attribute>
  4   <xsl:attribute name="font-size">6px</xsl:attribute>
  5   <xsl:attribute name="font-weight">normal</xsl:attribute>
  6   <xsl:attribute name="background-color">#f8f8f8</xsl:attribute>
  7   <xsl:attribute name="border-style">solid</xsl:attribute>
  8   <xsl:attribute name="border-width">0.1px</xsl:attribute>
  9   <xsl:attribute name="border-color">#777777</xsl:attribute>
 10 </xsl:attribute-set>

在上面的设置中，我们定义了文本的对齐方式、字号的大小、子的粗细、背景颜色及边界线的样式。在样式表中，还有很多类似这样的设置，例如admonition.properties 、 revhistory.table.properties等，都是依样画葫芦。

titlepage.templates.xml就是titlepage的模板文件，这个文件在目录docbook-xsl-1.79.1/fo下面。首先我们需要对里面的“book”部分进行修改，修改成如下的样子：

  1 <t:titlepage t:element="book" t:wrapper="fo:block">
  2     <t:titlepage-content t:side="recto">
  3       <mediaobject/>
  4       <title
  5              t:named-template="division.title"
  6              param:node="ancestor-or-self::book[1]"
  7              text-align="left"
  8              font-size="&hsize5;"
  9              space-before="&hsize5space;"
 10              font-weight="normal"
 11              font-family="{$title.fontset}"/>      
 12       <subtitle
 13              text-align="left"
 14              font-size="&hsize2;"
 15              font-weight="normal"
 16              space-before="&hsize4space;"
 17              font-family="{$title.fontset}"/>  
 18       <corpauthor font-size="&hsize0;"
 19              text-align="left"
 20              font-weight="normal" 
 21              keep-with-next.within-column="always"
 22              space-before="2in"/>  
 23       <authorgroup space-before="2in"/>
 24       <author font-size="&hsize0;"
 25              text-align="left"
 26              font-weight="normal" 
 27              space-before="&hsize2space;"
 28              keep-with-next.within-column="always"/> 
 29       <itermset/>
 30     </t:titlepage-content>
 31 
 32   <t:titlepage-content t:side="verso">
 33       <title
 34              t:named-template="book.verso.title"
 35              font-size="&hsize2;"
 36              font-weight="bold"
 37              font-family="{$title.fontset}"/>
 38       <corpauthor/>
 39       <authorgroup t:named-template="verso.authorgroup"/>
 40       <author/>
 41 
 42       <othercredit/>
 43       <copyright/>
 44       <pubdate/> 
 45       <releaseinfo/>         
 46       <revhistory/>       
 47       <abstract/>
 48       <legalnotice font-size="7pt" background-color="#f5f5f5" space-before="1em"/>
 49   </t:titlepage-content>
 50   <t:titlepage-separator>
 51       <fo:block break-after="page"/>
 52   </t:titlepage-separator>
 53   <t:titlepage-before t:side="recto">
 54   </t:titlepage-before>
 55   <t:titlepage-before t:side="verso">
 56       <fo:block break-after="page"/>
 57   </t:titlepage-before>
 58 </t:titlepage>

上面的代码虽然有点长，但很容易阅读，基本就说了两个事：在recto或verso页上显示哪些内容、用什么样的样式显示。

模板文件的生成需要刚才修改过的titlepage.templates.xml文件，及docbook-xsl-1.79.1/template/titlepage.xsl文件，还需要xsltproc这个命令。先将titlpage.templates.xsl做备份保存，然后执行如下的命令：

xsltproc --output titlepage.templates.xsl template/titlepage.xsl titlepage.templates.xml

这样，新的titlepage.templates.xsl文件就生成了。

我总感觉这里有点奇怪，用xsl生成xsl？ 但docbook官方就是这么定义的。

除了titlepage外，inline和pagesetup也需要定义模板，但不用修改xml文件了，可以参考fo/inline.xsl和fo/pagesetup.xsl文件和前面提到的相关站点。

在serif字体的选择上，可能最普遍的是用simsun字体，在正文部分使用simsun字体是不错的选择。每台windows的fonts目录里都有这款字体。但它的粗体在fop将文档转换为pdf的时候似乎并不美观。simsun属于商业字体。

另外一个选择就是前面我们下载的source-han-serif。

非衬线字体，文泉驿正黑、SimHei及微软雅黑等都属于这一类。可以根据自己的喜好来选择。SimHei和微软雅黑与simsun一样，属于商业字体，在正式场合使用的时候要注意版权问题。

另外一个选择就是前面我们下载的source-han-sans。

等宽字体，文泉驿微米黑属于这一类。当然，也可以从自己的操作系统中寻找合适的等宽字体。对于等宽字体，我还是非常推荐source-han-mono的。

Source Han字体是Aodbe和Google赞助，完全开源的字体。在Google称为Noto。

Source Han的设计团队比较强大。字形设计还是非常不错的，特别是sans部分，和其他的黑体比较起来，我感觉非常好看，非常适合作为标题的字体。

weight值一共有七个。

mono字体的粗斜全都有了。