Working with Docbook on Windows（在Windows下使用Docbook）

http://www.napcsweb.com/blog/2008/03/03/working-with-docbook-on-windows/
Posted by Brian in Howto, snacks, tips (March 3rd, 2008)

Setting up a toolchain for working with Docbook on Windows often requires setting things up using Cygwin. Many people are just simply not willing to do that. This tutorial will show you how to set up a native environment to work with Docbook, and show you how to make CHM and PDF files on Windows.
通常情况下，在设置Windows环境下的Docbook时都需要用到Cygwin。但是有些人不想那么麻烦。这篇入门指导将会介绍如何在Windows自然环境下配置Docbook，以及如何制成CHM和PDF文件。
Thanks to http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/docbooksys/segmentedhtml/ch03s03.html#DocBookSys-Chapter3-XML-Install-libxml-Windows for much of this information.
感谢http://supportweb.cs.bham.ac.uk /documentation/tutorials/docsystem/build/tutorials/docbooksys/segmentedhtml/ch03s03.html#DocBookSys-Chapter3-XML-Install-libxml-Windows 提供丰富的信息指导。
Getting the tools
The tools you need to work with Docbook XML and XSTL are all available on Windows. The first thing you need to do is visit http://www.zlatkovic.com/pub/libxml/ (new window) and grab the latest versions of
    * libxml2
    * libxslt
    * iconv
Download each and unzip the contents of the folder to c:\windows or another location on your path. For reference, these files are the ones you’re looking for:
iconv.exe
libexslt.dll
libxml2.dll
libxslt.dll
xmlcatalog.exe
xmllint.exe
xsltproc.exe
If you feel better about putting these in their own folder, that’s fine as long as you add the new folder to your path.
下载工具
您需要在 Windows下配置好Docbook XML和XSTL。首先需要访问 http://www.zlatkovic.com/pub/libxml/ 下载最终版本的
    * libxml2
    * libxslt
    * iconv
下载并且解压缩到 c:\windows或者其他文件夹下。请确认一下这些文件：
iconv.exe
libexslt.dll
libxml2.dll
libxslt.dll
xmlcatalog.exe
xmllint.exe
xsltproc.exe
如果您觉得更想让他们在自己的文件夹下，那一定要把文件夹添加到您的路径下。（译者注：就是添加到Path环境变量里。）
Getting the Stylesheets
In order to build a book, you need to have the XSLT stylesheets so you can transform your XML into a pretty-looking book with a table of contents and nicely formatted text.
Download the docbook-xml-ns files from sourceforge: http://sourceforge.net/project/showfiles.php?group_id=21935
Unpack to your c:\ drive and then rename the extracted folder to c:\docbook-xsl
下载样式表
为了创建一本书，您需要有XSLT样式表来让您可以把XML文件变成精美的带有目录的图书和有着漂亮格式的文本。
从sourceforge下载docbook-xml-ns文件：http://sourceforge.net/project/showfiles.php?group_id=21935
解压缩到c:\docbook-xsl
Generating PDFs
In order to create a PDF, you have to first convert to the FO format and then use a Java library to convert the FO to a PDF. Apache FOP does this for you. You’ll need to have a JRE (Java Runtime) installed though. Visit http://java.sun.com/ for that.
创建PDF文件
为了创建PDF文件，您需要首先把文件转换为FO格式的文件，然后使用Java库把 FO文件转化为PDF文件。Apache的FOP就是为您而制的。不过您需要先安装好JRE（Java 运行环境）。请访问http://java.sun.com/ 。
Get FOP to build PDFs
Download FOP at http://www.uniontransit.com/apache/xmlgraphics/fop/fop-0.94-bin-jdk1.4.zip and unzip it to a temp location. Copy all .jar files in build/ and lib/ to your Java installation’s lib/ext folder. On my system it’s C:\Program Files\Java\jre1.5.0_11\lib\ext. Your system will differ depending on your installed version of Java.
Next, download OFFO-hyphenation from http://offo.sourceforge.net/index.html and grab the offo-hyphenation-fop-stable.zip file from the downloads page and put the jar files in the same folder as the FOP files.
下载创建PDF文件的FOP
在http://www.uniontransit.com/apache/xmlgraphics/fop/fop-0.94-bin-jdk1.4.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相同的文件夹里。
Building your first book
创建您的第一本书
Create a project folder called “my_book” and create a new file called “book.xml” in this folder.
创建一个叫“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>
Then create a chapter for your book. Create the file chapter1.xml in your project folder with this content:
然后在您的书里创建一个章节。在您的项目文件夹里创建内容如下的 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>
Notice that the chapter and book each have their own doctype, This is really important. Each chapter file needs to have this structure in order to work properly.
需要注意的是章节和书都有它们自己的文档类型。每一个章节文都需要合适的结构。
Generating HTML from the document
用文档生成HTML文件
The easiest way to use Docbook is to export to HTML. Execute this command to create an HTML version of your book:
可以很容易的把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目录下既可。）
Creating a makefile to build the PDF
建立一个用于创建PDF文件的makefile文件
The PDF creation process is similar to the HTML process but it does require two steps. You need to first convert the document to the FO file format. Then you use FOP to convert it to the PDF. We can automate this by using Ruby.
创建PDF文件与创建 HTML文件的过程类似，但是需要两步。您需要首先把文档转换为FO文件格式。然后，把FOP文件传唤为PDF文件。我们可以使用Ruby来自动完成。（译者注：作者的博客上有很多关于Ruby的文章，所以作者理所当然的使用Ruby来创建脚本。要运行下面的脚本自然要安装好Ruby环境。可以访问 http://www.ruby-lang.org/en/downloads/）
Create a Ruby file in your project folder called “make”. You’ll use this file to build the PDF of your book.
在项目文件夹里创建一个名为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"
Now, build your book:
现在创建您的书：
ruby make book
(译者注：实际命令应该写成ruby make.rb book)
Creating a Help File
创建Help文件
Generating a Windows HTML Help file (CHM) is pretty similar to the way you make a PDF. You first need to make the HLP file using xsltproc, and then you use a commandline tool to build the CHM.
创建Windows HTML 帮助文件（CHM）的方法和创建PDF非常相似。您第一步需要使用xsltproc制作出HLP文件，并且使用命令行工具创建CHM文件。
Grab a copy of Microsoft’s HTML Help Workshop here and install it. Open a command prompt and copy the hhc file to the c:\windows directory so that the file is on your path.
从这里下载（译者注：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
(译者注：\是我加的)
Next, we can use Ruby to make a file to create another build file. Create a file called “make_chm” in your project folder.
下一步，我们创建另外一个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"
Summary
总结
Docbook is a really great way to create books, tutorials, and documentation in a format that can be transformed into various other formats. It’s extremly easy to work with in Windows too!
Docbook是一种很伟大的创建图书、入门向导和文章的方式，并且文档能够被转换为各种格式。在 Windows下也能轻松使用了！