Docbook开发手记

第 4 章 Docbook参考资料

特点：最权威解释的。

关于docbook的最权威的，官网的教程。

有任何问题，上去找，一般都可以找到答案或参考。

特点：参数大全

关于各种输出格式，HTML，FO（PDF），manpage，website等等的参数方面，有哪些参数，具体如何配置，都可以去这里找到。

特点：（除了本身教程写的好之外，）docbook的xml源码可下载供参考

关于C编程的概念和知识，解释的很透彻，值得一看。

除了教程写的很有价值，其还把docbook的xml源码也公开了，可下载做参考。

相应html也可打包下载。

所以很适合，最开始写docbook源码的时候，做为参考代码。

特点：Norman Walsh写的，最权威的关于docbook5的参考资料

放在后面介绍，并不代表不重要。只是因为是英文写的，不适合做入门资料。

适合当参考书，有需要的时候去找相关内容再细看。

特点：入门的参考教程

解释的很详细，适合入门者。东西解释的够全，很多知识点都值得参考参考。

只不过其搭建环境是Mac，不是很多人常用的Windows。

特点：部分内容可做参考

台湾人写的。解释的比较详细。等遇到相关知识，也许可以做参考。

特点：很多例子，还是可以参考参考的。而且内容也很全面，从环境搭建到例子，全部都有。还介绍了用各种工具，转换成各种不同的格式的用法。

简单介绍了如何写docbook，其中有关于用Eclipse平台的方法。

这里一张图片，就总结了，关于Docbook的各种方法，生成各种格式的文件。

中文的docbook的教程，写的还不错，有空可以参考参考。

Docbook的FAQ

里面详细介绍了，各种常见问题。

个人觉得比较有帮助的有：

Docbook tools

其中记录了，关于Docbook相关的一些工具，比如xsltproc等相关的问题和解决办法

Docbook的主页

算是Docbook的入口了，想要找一切关于Docbook的东西，都可以先去那里看看，说不定会有意外发现。

尤其是DocBook的表格CALS和HTML的表格的比较，很值得看看：

Comparison of CALS and HTML tables

其中，也有关于表格中列的宽度的介绍：

Column widths

之前别的教程中，最开始部分介绍的关于添加字体的内容，估计就是参考官网的这部分的解释：

Chapter 13. Print customizations – Adding a font

主要分两种方法，一种是写对应的xsl配置内容，放到自己的xsl文件中去。

另外一种就是使用相应的参数控制。

对应的这些参数有哪些，以及具体含义，在这里可以找到（注：此处是用的xsl是docbook-xsl-ns-1.76.1）：

DocBook XSL Stylesheets: Reference Documentation

（也可以下载其pdf版本，留着当做参考书）

其中，

对于HTML的参数都在这里：1. HTML Parameter Reference

对于（用fo生成的）PDF的参数控制，都在这里：2. FO Parameter Reference

关于如何使用这些参数，可以参考一些相关的帖子：

ulink.show：【已解决】去掉docbook中输出的pdf中，除了带链接的文字之外的那个链接地址

fop1.extensions：【已解决】Docbook的pdf，去除正文对于标题的缩进indent + 【顺带实现】给docbook的pdf添加bookmark书签的功能

那么可以在使用xsltproc的时候，添加对应的参数即可。

对于使用fop的话：

如果是用的0.20.5或更早的版本，参考这里：Processor Extensions – fop.extensions添加这个参数：

--stringparam fop.extensions 1

如果是用的0.90及更新的版本，参考这里：Processor Extensions – fop1.extensions添加这个参数：

--stringparam fop1.extensions 1

我现在所用的fop是1.0的，所以用的是fop1.extensions。

折腾其他参数的过程中，无意间看到：

使用FOP将中文DocBook xml转换成pdf的实现记录

中是将参数写成这样的：

<xsl:param name=”body.font.family”>simsun</xsl:param>
<xsl:param name=”monospace.font.family”>simsun</xsl:param>
<xsl:param name=”title.font.family”>simhei</xsl:param>
<xsl:param name=”saxon.character.representation” select=”‘native’”/>
<xsl:param name=”admon.graphics” select=”1″/>
<xsl:param name=”section.autolabel” select=”1″/>
<xsl:param name=”section.label.includes.component.label” select=”1″/>
<xsl:param name=”table.borders.with.css” select=”1″/>
<xsl:param name=”use.extensions” select=”1″/>
<xsl:param name=”tablecolumns.extension” select=”0″/>
<xsl:param name=”callout.unicode” select=”1″/>
<xsl:param name=”callout.unicode.start.character” select=”10102″></xsl:param>
<xsl:param name=”variablelist.as.blocks” select=”1″></xsl:param>
<xsl:param name=”callout.graphics” select=”0″/>
<xsl:param name=”fop.extensions” select=”1″/>
<xsl:param name=”hyphenate”>false</xsl:param>
<xsl:param name=”l10n.gentext.default.language” select=”‘zh’”/>
<xsl:param name=”paper.type” select=”‘A4′”/>
<xsl:param name=”draft.mode” select=”‘no’”/>
<xsl:param name=”generate.toc”>
 
            

而与此相对，我之前都是写到–stringparam中的，所以，将原先的命令：

xsltproc.exe --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --stringparam bibliography.numbered 1 --stringparam ulink.show 1 --stringparam ulink.footnotes 1 --stringparam table.cell.border.color green --stringparam table.frame.border.thickness 2pt --stringparam fop1.extensions 1 --stringparam body.start.indent 0pt --xinclude -o ../output/fo/MPEG_VBR.fo /home/CLi/develop/docbook/config/docbook-xsl-ns-1.76.1/fo/docbook_crl.xsl MPEG_VBR.xml

转化为：

xsltproc.exe --xinclude -o ../output/fo/MPEG_VBR.fo /home/CLi/develop/docbook/config/docbook-xsl-ns-1.76.1/fo/docbook_crl.xsl MPEG_VBR.xml

加上docbook_crl.xsl中的相关配置：

<xsl:param name="admon.graphics" select="1"/>
<xsl:param name="section.autolabel" select="1"/>
<xsl:param name="section.label.includes.component.label" select="1"/>
<xsl:param name="bibliography.numbered" select="1"/>
<xsl:param name="ulink.show" select="1"/>
<xsl:param name="ulink.footnotes" select="1"/>
<xsl:param name="table.cell.border.color">green</xsl:param>
<xsl:param name="table.frame.border.thickness">2pt</xsl:param>
<xsl:param name="fop1.extensions">1</xsl:param>
<xsl:param name="body.start.indent">0pt</xsl:param>
 
            

这样，每次就不用输入那么多的配置参数了。

而需要额外的参数配置，也就都可以写到xsl文件中了。

此时，也才理解，原来DocBook XSL Stylesheets: Reference Documentation

中的HTML和FO（PDF）的那么多参数，每个都有个语法解释，比如：table.cell.border.color中的：

<xsl:param name="table.cell.border.color"></xsl:param>
 
            

指的就是，将此配置，写入到xsl文件中。而之前一直都不知道，都傻傻地加入到xsltproc的参数中去了。

包括xsltproc中如何使用catalog的内容：

这里：Docbook Stylsheet Customisation

列出了常见的一些配置参数，包括：章节编号的深度控制，给tip和warning加图片，给programlisting加背景色等。

如果想要通过Docbook建立网站，可以参考此文：How to use the Docbook Website system

这里有专门的别人已经帮你搭建好的，基于ant的docbook的开发环境：ant4docbook

目前看到的已支持多种格式：html，pdf，epub，docx，rtf，

ant的官网中，也有介绍：Create DocBook XML based documentation with Ant