初识DocBook的一些经历

缘起

最近在研究JPF，因JPF的代码库使用的是Mercurial(一种分布式的源码控制系统),因此而接触到有关Mercurial的一本著作《Mercurial:The DefiniteGuide》。本着好奇心就去看了一下这本书,没想书的源码可以获取的(若安装了Mercurial工具的话,在shell中键入:hgclonehttp://bitbucket.org/bos/hgbook).然后我就跑过去看看clone下来的东西如何如何,进入目录后一看,当时我就傻眼了,目录中内容是这样的:

除了Makefile稍微有点亲切感意外,其他的都是些什么？？！！我于是乎把作者的原话又读了一遍:"Ipublish the sourcecode for this bookasaMercurial repository.Please feel welcome to clone it, makemodifications to your copy, and send me changes."作者提供源码的要求只有一个：提供修改反馈

解决方案

解1

   如果只是使用看《Mercurial:The DefiniteGuide》这本书的话,最佳解决方法就是在网上Download一下,google一下就很快找到这份文档了。这里我使用网盘做了个链接，里面有两个pdf文件(都是英文版的,编译的中文版的不能用)。一份是down的,一份是自己编译:http://pan.baidu.com/share/link?shareid=1673915094&uk=556148328

解2

如果想自己编译的话,那就稍微麻烦一点了。(编译中文版的不一定会成功-各种问题,太吓人了)

首先要从http://hgbook.red-bean.com/将文档的源码拷贝下来。其次，仔细阅读上图中的README(介绍各个目录下文件的情况)和README.BUILD(如何编译源码之类)这两个文件。如果好好把这两个文件读一读,可以避免满互联网的搜方法找答案这种费时有伤神的办法。

II.COMPILING THE DOCS

1.Install XML DTD and XSL stylesheets for DocBook

%sudo apt-get install docbook-xml docbook-xsl

2.Install libxml2-utils

%sudo apt-get install libxml2-utils

3.Install graph drawing and patches tools

%sudo apt-get install graphviz inkscape patchutils

4.Install pdf support

%sudo apt-get install openjdk-6-jdk docbook-xsl-saxon libsaxon-java fop

TheMakefile will actually invoke $FOP_HOME/fop.sh, you should do

sometrick, let fop'sCLASSPATHinclude(包含)saxon.jaranddocbook-xsl-saxon.jar.

5.Configure XML Catalogs

Fornon pdf output, we use xsltproc for XSLT process, xsltproc usesystem catalog files automatically, usually /etc/xml/catalog. Usersdo not need to care about it.

Forpdf output, we need use the xsl extensions (docbook-xsl-saxon), so wemust

createfile $JAVA_LIB/CatalogManager.properties like this:

catalogs=/etc/xml/catalog

relative-catalogs=true

static-catalog=yes

catalog-class-name=org.apache.xml.resolver.Resolver

verbosity=1

6.Create Makefile.vars

Pleasecreate your Makefile.vars from Makefile.vars.tmpl.--需要注意的是,Makefile.vars中的变量的路径一定要配置正确.Makefile.vars文件中的内容如下:

#po4a (>= 0.36.1): Only for PO based translation !

#PO4A_HOME=/usr/bin

#PO4A_LIB=/usr/share/perl5

PO4A_HOME=/home/dongsheng/vcs/svn/i18n-zh/trunk/lib/po4a

PO4A_LIB=$(PO4A_HOME)/lib

#saxon65.jar, saxon65-dbxsl.jar, xml-commons-resolver-1.2.jar: Onlyfor pdf format !

#JAVA_LIB=/usr/lib/jvm/java-6-openjdk-i386/lib

JAVA_LIB=/home/dongsheng/vcs/svn/i18n-zh/trunk/lib/share/java

#fop (>= 0.9.6): Only for pdf format !

#FOP_HOME=/usr/bin

FOP_HOME=/home/dongsheng/vcs/svn/i18n-zh/trunk/lib/fop

#docbook-xsl (>= 1.74.3): Only for ePub format !--不需要考虑,因为对这个格式的文件不感兴趣

DB2EPUB=/home/dongsheng/vcs/svn/i18n-zh/trunk/lib/docbook/docbook-xsl/epub/bin/dbtoepub

注意:使用‘#’注释并用标志出来的是使用README.BUILD提供的方法来编译的。其实没用注释提供了的是另一个方法：使用i18n-zh提供的工具来处理,获取i18n-zh代码工具的方法是通过svn将i18n-zh中的文件和代码签出,命令行为:svn co http://i18n-zh.googlecode.com/svn/。

注意,如果是使用的i18n-zh提供的工具进行处理的话,只有graphviz,inkscape这两个工具包是必须的,其他的工具包i18n-zh都可由提供.

7.Make

Run'make' for more details, for example:

*make all document(pdf, epub, html and html-single for all languages)

%make all

*make english document(pdf,epub,htmlandhtml-singlefor all languages)

%make LINGUA=en all

*make Chinese document(pdf,epub,htmlandhtml-singlefor all languages)

%make LINGUA=zh all

*make Chinese pdf document

%makeLINGUA=zh pdf

注意:这里只是README.BUILD中的一部分。由此,在编译软件之前后者出错之后,仔细查看README,INSTALL,FAQ之类的文件就可以直接解决遇到的很多问题。如果这样还不能解决问题的话,再开始满互联网的搜索或者到论坛上提问。

我使用makeLINGUA=zhpdf时,在处理字体的是有报错,原因是我的机器没有安装相应的字体。Ubunut下安装字体,本来以为又是一堆命令行(mkfontscale、mkfontdir、fc-cache),参考了http://blog.ubuntusoft.com/installing-ubuntu-easiest-way-fonts.html#.UgdJMCEW3Zg后发现,已经变得很简单了,点击安装就好了。以微软雅黑为例，点击右下角的InstallFont就行了(不要惊讶,就是这么简单)。

将字体安装好,配置好Makefile.vars,新配置的文件修改如下(这个可能因人而异,因为每个人签出的版本都是不一样的)

PO4A_HOME=/home/xiajian/vcs/svn/trunk/lib/po4a

PO4A_LIB=$(PO4A_HOME)/lib

JAVA_LIB=/home/xiajian/vcs/svn/trunk/lib/share/java

FOP_HOME=/home/xiajian/vcs/svn/trunk/lib/fop

编译之后：

一些理论(来自《UNIX编程艺术》)

DocBook是为大规模,复杂技术文档而设计的SGML/XML文档类型定义。DocBook是纯粹的结构性的标记语言，支持转换到HTML,XHTML,PDF,Windows帮助,PostScript。几个主要的开源项目(Linux文档项目,FreeBSD,Apache,Samba,GNOME,KDE)使用DocBook作为首要格式。

DocBook:支持结构层标记,返对表示层标记,XML-DocBook开源的工具链的实现。

文档格式器,通晓文档的整个结构并将样式表应用到其中。文档类型/DTD。DocBook为XML的方言,是一个巨大的DTD-DocumentType Definition(400个标签tag)。

     注意:格式器需要两个隐含的输入是DTD和样式表。

DocBook工具链:DocBook-->XHTML(xmlto,引擎-xsltproc|Saxon|Xalan)

2003年的XML-DocBook工具链。

存在FOP(FO-to-PostScript)的XML-DocBook工具链(也就是编译本文中描述的文件的所用的工具链)

一些有趣的东西

1.为了能够编译DocBook,我前后安装了这样的一些东西:dot,inkscape,po4a,fop。

po4a项目致力于软件文档翻译框架，它可以将多种格式(manpage, xml, docbook, xhtml, wml, tex, texinfo, latex, asciidoc, dia,guide, kernelhelp, pod, ini等)转换为PO文件进行翻译，待翻译完成再将PO文件转换为原来的格式。目前，po4a的最新版本是0.44，其开发还在活跃的进行之中。GentooLinux的中文手册翻译就是使用了po4a。po4a的项目主页在这里http://po4a.alioth.debian.org/

2.在hgbook的Makefile.vars.tmpl文件中看到这样的/home/XXX/vcs/svn/i18n-zh/trunk/lib/po4a这里目录很有可能是subversion服务器中相关的东西。于是google了一下,确实有相关的网站:http://i18n-zh.googlecode.com/svn/trunk/,但是不清楚i18n-zh到底只干什么的,又继续google了一下,发现i18n-zh是一个很牛的组织，其组织的目标是“致力于常用软件的中文化工作，推广自由软件"。

一些问题

1恐怖的Java错误

[ERROR]FOP - Exception <org.apache.fop.apps.FOPException: Failed toresolve font with embed-url'../../fonts/fzfs.ttf'>org.apache.fop.apps.FOPException: Failed toresolve font with embed-url '../../fonts/fzfs.ttf'

2.奇怪的异常

FOP_HOME:/home/xiajian/vcs/svn/trunk/lib/fop

[WARN]FOUserAgent - Font "sans-serif,normal,900" not found.Substituting with "sans-serif,normal,700".

[WARN]FOUserAgent - Font "SimHei,normal,900" not found.Substituting with "SimHei,normal,700".

[WARN]FOUserAgent - Font "sans-serif,normal,600" not found.Substituting with "sans-serif,normal,700".

[WARN]FOUserAgent - Font "SimHei,normal,600" not found.Substituting with "SimHei,normal,700".

[WARN]FOUserAgent - Glyph "序"(0x5e8f) not available in font "Times-Roman".

[WARN]FOUserAgent - Glyph "言"(0x8a00) not available in font "Times-Roman".

[WARN]FOUserAgent - Glyph "技"(0x6280) not available in font "Times-Roman".

[WARN]FOUserAgent - Glyph "术"(0x672f) not available in font "Times-Roman".

[WARN]FOUserAgent - Glyph "背"(0x80cc) not available in font "Times-Roman".

[WARN]FOUserAgent - Glyph "景"(0x666f) not available in font "Times-Roman".

[WARN]FOUserAgent - Glyph "谢"(0x8c22) not available in font "Times-Roman".

[WARN]FOUserAgent - Glyph "你"(0x4f60) not available in font "Times-Roman".

[WARN]FOUserAgent - Glyph "系"(0x7cfb) not available in font "Courier".

[WARN]FOUserAgent - Glyph "列"(0x5217) not available in font "Courier".

[WARN]FOUserAgent - Glyph "序"(0x5e8f) not available in font "Courier".

[WARN]FOUserAgent - Glyph "状"(0x72b6) not available in font "Courier".

[WARN]FOUserAgent - Glyph "态"(0x6001) not available in font "Courier".

[WARN]FOUserAgent - Glyph "等"(0x7b49) not available in font "Courier".

[WARN]FOUserAgent - Glyph "宽"(0x5bbd) not available in font "Courier".

[WARN]FOUserAgent - Glyph "标"(0x6807) not available in font "Courier".

[WARN]FOUserAgent - Line 1 of a paragraph overflows the available area by30408 millipoints. (See position 550:736)

[WARN]FOUserAgent - Line 1 of a paragraph overflows the available area by47809 millipoints. (See position 556:769)

[WARN]FOUserAgent - Line 1 of a paragraph overflows the available area by47809 millipoints. (See position 573:714)

小结:

1.遇到问题要冷静思考

2.不要过分迷恋自己的能力,不要重复制造轮子,能用别人的就用别人的。记住鲁迅先生的拿来主义,这样可以节约时间。

3.DocBook确实是个不错的工具,文档的重要性。

参考资料:

[1]UNIX编程艺术,Eric S.Raymond著,姜宏等译.电子工业出版社

[2]i18n-zh官方wiki:https://code.google.com/p/i18n-zh/wiki/