在Windows上使用DocBook写帮助文档

原文链接：http://flyingskyfu.spaces.live.com/blog/cns!177C77405DD0ABCA!936.entry?wa=wsignin1.0&sa=545002127

 

最近用DocBook写dbk文档，写好后编译为chm，然后集成到项目。特总结了这篇文章 (大部分为抄写自 http://www.yeeyan.com/articles/view/3911/16049)
通常情况下，在设置Windows环境下的Docbook时都需要用到 Cygwin。但是有些人不想那么麻烦。这篇入门指导将会介绍如何在Windows自然环境下配置Docbook，以及如何制成CHM和PDF文件。
感谢http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem /build/tutorials/docbooksys/segmentedhtml/ch03s03.html#DocBookSys-Chapter3-XML-Install-libxml-Windows 提供丰富的信息指导。
下载工具
您需要在Windows下配置好Docbook XML和XSTL。首先需要访问 http://www.zlatkovic.com/pub/libxml/ 下载最终版本的
    * libxml2
    * libxslt
    * iconv
下载并且解压缩到D:\Softwares_bak\Develop\DocBook。请确认一下这些文件：
iconv.exe
libexslt.dll
libxml2.dll
libxslt.dll
xmlcatalog.exe
xmllint.exe
xsltproc.exe
并把D:\Softwares_bak\Develop\DocBook文件夹添加到环境变量Path中。（译者注：就是添加到Path环境变量里。）
下载样式表
为了创建一本书，您需要有XSLT样式表来让您可以把XML文件变成精美的带有目录的图书和有着漂亮格式的文本。
从 sourceforge下载docbook-xml-ns文件：http://sourceforge.net/project/showfiles.php?group_id=21935

解压缩到D:\Softwares_bak\Develop\DocBook\docbook-xsl-ns
创建PDF文件
为了创建PDF文件，您需要首先把文件转换为FO格式的文件，然后使用Java库把FO文件转化为PDF文件。Apache的FOP就是为您而制的。不过您需要先安装好JRE（Java 运行环境）。请访问http://java.sun.com/ 。
下载创建PDF文件的FOP
在 (http://www.apache.org/dist/xmlgraphics/fop/binaries/fop-0.95-bin.zip) 下载FOP文件并且解压缩到一个临时目录中。拷贝所有 build/ 和 lib/目录中的 .jar 文件到您Java安装文件夹的 lib/ext 目录中。在我的系统下是 C:\Program Files\Java\jre1.5.0_11\lib\ext 。您的系统的具体情况主要是由您安装的Java的版本决定的。
下一步，下载从http://offo.sourceforge.net/index.html下载 OFFO-hyphenation 并且把 offo-hyphenation-fop-stable.zip文件里的jar文件都复制到和FOP相同的文件夹里。
创建您的第一本书
创建一个叫“my_book”的项目文件夹，并且在这个文件夹里创建一个叫“book.xml”的文件。
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
<bookinfo>
<title>My Simple Book</title>
</bookinfo>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="chapter1.xml"/>
</book>
然后在您的书里创建一个章节。在您的项目文件夹里创建内容如下的chapter1.xml文件：
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="chapter1">
<title>Introduction</title>
<para>This is just a simple book.</para>
</chapter>
需要注意的是章节和书都有它们自己的文档类型。每一个章节文都需要合适的结构。
用文档生成HTML文件
可以很容易的把Docbook输出成HTML文件。执行这个命令为您的书生成一个HTML版本：
   xsltproc --xinclude --output book.html c:/docbook/xsl/html/docbook.xsl book.xml
（译者注：原文如此，其实应该是 xsltproc --xinclude --output book.html c:/docbook-xsl/html/docbook.xsl book.xml
我第一运行是提示我xsltproc缺少zlib1.dll。后来发现，还需要在http://www.zlatkovic.com/pub/libxml/ 中下载zlib压缩包，然后解压缩到Windows目录下既可。）
建立一个用于创建PDF文件的makefile文件
创建PDF文件与创建HTML文件的过程类似，但是需要两步。您需要首先把文档转换为FO文件格式。然后，把FOP文件传唤为PDF文件。我们可以使用 Ruby来自动完成。（译者注：作者的博客上有很多关于Ruby的文章，所以作者理所当然的使用Ruby来创建脚本。要运行下面的脚本自然要安装好 Ruby环境。可以访问http://www.ruby-lang.org/en/downloads/）
在项目文件夹里创建一个名为make的Ruby文件。您可以用这个文件创建您的书的PDF版本。（译者注：如果您不熟悉Ruby的话，请注意：Ruby文件如果是UTF-8格式的话，不能加BOM）
file = ARGV[0]
cmd1 = "xsltproc --xinclude --output #{file}.fo c:/docbook-xsl/fo/docbook.xsl #{file}.xml "
cmd2 = "java org.apache.fop.cli.Main -fo #{file}.fo -pdf #{file}.pdf"
puts "Building FO file"
`#{cmd1}`
puts "Building PDF"
`#{cmd2}`
puts "Cleaning up"
`del #{file}.fo`
puts "Done"
现在创建您的书：
ruby make book
(译者注：实际命令应该写成ruby make.rb book)
创建Help文件
创建Windows HTML 帮助文件（CHM）的方法和创建PDF非常相似。您第一步需要使用xsltproc制作出HLP文件，并且使用命令行工具创建CHM文件。
从这里下载（译者注：http://go.microsoft.com/fwlink/?LinkId=14188）并安装Microsoft’s HTML Help Workshop。打开命令行拷贝hhc文件到c:\windows目录中或者您自己的路径里。
copy "c:\Program Files\HTML Help Workshop"\hhc.exe c:\windows
(译者注：\是我加的)
下一步，我们创建另外一个Ruby文件。在您的目录文件夹里创建一个叫做“make_chm”的文件。
file = ARGV[0]
cmd1 = "xsltproc --xinclude c:/docbook-xsl/htmlhelp/htmlhelp.xsl #{file}.xml"
cmd2 = "hhc htmlhelp.hhp"
puts "Building HLP temporary files"
`#{cmd1}`
puts "Building CHM"
`#{cmd2}`
puts "Cleaning up"
`rename htmlhelp.chm #{file}.chm`
`del *.hhp`
`del *.hhc`
`del *.html`
puts "Done"
总结
Docbook是一种很伟大的创建图书、入门向导和文章的方式，并且文档能够被转换为各种格式。在Windows下也能轻松使用了！