| 第 1 章 制作第一份DocBook文档 | ||
|---|---|---|
 |  | |
| 第 1 章 制作第一份DocBook文档 | ||
|---|---|---|
| | | |
目录
前面已经提到过，DocBook主要分为SGML和XML两个版本，不论哪个版本，都称为DocBook DTD（DocBook Document Type Definition ，即DocBook文档类型定义）。在DocBook DTD中，详细的描述了所有的标签。在这份文档中，我们使用的是XML版本的DocBook DTD。从目前的状态来看，SGML版本使用的已经非常少。
DocBook的入门是有一定门槛的，需要很多方面的配合，才能产出一份不错的文档。但一旦入门，并开始使用以后，对后期的文档制作效率和质量都是有极大提高的。要制作一份精美的DocBook文档，需要如下的一些组件：
DocBook规范成熟的版本主要有两个：4.x和5.x，在这份小册子里我们采用的是5.0版本。
DocBook 5的标签请参考这个站点：https://tdg.docbook.org/tdg/5.0/docbook.html
首先，需要按照DocBook DTD的规范要求，书写我们的xml文档。这是一件容易的事情，虽然有很多的标签，但每个标签的含义都非常明显，并且DocBook的官方网站给出了所有标签的解释，以及它的父节点和子节点。下面的示例就是这个小节真实的样子：
<chapter><title>制作第⼀份DocBook⽂档</title> <para>前面已经提到过... ...</para> <para>DocBook的入门是有一定门槛的... ...</para>
有了DocBook格式的xml文件之后，我们需要将这些xml转换成人们容易阅读的格式，如html或pdf格式。那不同标签所包含的内容用什么样的样式来显示呢？ 这就需要一套样式表。
DocBook的XSL样式表有三个版本：
这是最早的一个版本，也是最“细腻”、“成熟”的一个版本。是由OASIS组织之外的另外的一家公司Sagehill Enterprises开发。这份样式表的名叫DocBook-xsl，目前版本号是1.79.2。
这个版本是在1.0的基础上进行了相关的开发。但这个样式表的应用似乎没有1.0应用广泛。
这个版本是在XSLT 3.0成为了W3C的推荐标准之后开始开发的，主要的开发者就是前面提到的 Mr.Norman Walsh。这是一个全新的版本。在这个版本里有了很多新的理念。最主要的，就是在将文档生成为PDF时 ，建议使用CSS Paged Media技术。也就是使用CSS样式表来生成PDF文件。
样式表有关内容请参考：https://xsltng.docbook.org/
这份小册子使用的是DocBook5.0和XSLT 1.0。及我们后面要分享的也是DocBook5.0和XSLT 1.0。
有几种类型的字体需要我们提前准备好主要包括sans、serif、monospace等。后面会有详细的介绍。
有了DocBook格式的文件、DocBook-xsl样式表及字体，那还需要一些程序将这些东西生产出我们需要的html或pdf文件。主要包括xsltproc、saxon和fop等。
就像前面所描述的，我们首先需要搭建一个基础的环境。这个环境的搭建比较简单，没有一些额外的安装步骤，只需要我们把相关的样式表、程序等下载并解压缩，然后放置在合适的目录中就可以了。下表是需要的组件清单：
表 1.1. software
| No. | Name | Version |
|---|---|---|
| 1 | 操作系统 OS | Debian Linux 12 Bookworm |
| 2 | DocBook DTD | DocBook-5.0 |
| 3 | DocBook-xsl | DocBook-xsl-1.79.2 |
| 4 | java | jre-8u301-linux-x64 |
| 5 | saxon | saxon6-5-5 |
| 6 | xalan | xalan-j_2_7_2-bin |
| 7 | fop | fop-2.6-bin |
| 8 | xsltproc | 1.1.34 |
| 9 | fonts | 思源字体 |
为了叙述方便，我们建立一个专门的目录docware来存放这些组件。
下载地址：https://DocBook.org/xml/5.0/DocBook-5.0.zip
这个DTD其实也可以不用下载，这里面就是DocBook DTD。下载好解压缩以后，DocBook.dtd文件在dtd的目录里。
上面的链接给出的版本是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目录中。
![[提示]](themes/default/admon/tip.png) | 提示 |
|---|---|
可能会有人问，对于这些组件版本的选择有什么讲究？其实也有一个大致的原则，首先不用最新版，其次是我重点参考了Debian 12和Ubuntu 20的版本库里相应的版本。保证这些组件所使用的版本都是经过稳定的系统测试过的。 |
将这些组件下载到docware中，然后全部解压缩，基本的一个环境就算是搭建好了。后期还需要对fop的配置文件fop.xconf及XSL样式表进行很多的配置，到这里我们先把这些事情暂时一放。先写出第一份文档，然后再回过头来处理这些工作。
[2] fo = Formatting Objects。格式化对象，简单来说，就是xsl处理程序通过格式对象（fo）来决定哪些元素被放置在页面的哪些位置。这是一个由w3c维护的xsl标准的一部分。https://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section
| | | |
| 3. How ? |  | 2. 书写DocBook格式的xml文件 |
