1.2. 纯Windows环境下的Docbook开发环境的搭建
上一页  第 1 章 Windows下的Docbook的环境搭建  下一页

1.2. 纯Windows环境下的Docbook开发环境的搭建

[重要] docbook demo所有相关文件下载

和下面纯windows下docbook环境搭建有关的文件，可以在这里下载到：docbook5_demo_noTools.7z

此处介绍如何在纯Windows环境下（即不需要额外安装Cygwin等），而搭建最基本的Docbook环境。

使得可以生成对应的HTML和PDF。

以下内容，主要参考：一个简单的Docbook 5.0例子和在Windows上安装配置Apache FOP

此处之所以重新介绍一遍，主要目的在于，当前使用的fop 1.0的版本，可以省略关于fop字体设置的部分，以减少步骤。

1.2.1. 建立好文件夹

为了以后更好的使用和扩展Docbook环境，所以此处专门设计了一个简单的架构。

即，不是为了演示，就随便糊弄一下。

下面的架构搭好之后，真正想要使用docbook的人，就可以在此基础上，一点点的扩展功能了。

当然，此处搭建的环境，也尽量的保持简洁，此处暂时只支持生成我们所需要的HTML和PDF。

下面就是要搭建的docbook环境所对应的文件夹结构

请自行在某个文件夹，比如我的是E:\DevRoot\docbook,下面建立对应的文件夹。

books1
    |
    |-- docbook5_demo2
            |
            |-- output3
            |   |
            |   |-- fo4
            |   |-- html5
            |   |-- pdf5
            |
            |-- src6

config7
    |
    |-- docbook-xsl-ns-1.77.18
    |-- fop9

tools
    |
    |-- docbook-xsl-ns-1.77.110
    |   |
    |   |-- fo
    |   |-- html
    |   ...
    |
    |-- fop-1.011
    |   |
    |   |-- build
    |   |-- conf
    |   |-- ...
    |
    |-- xslt12
        |
        |-- bin
        |-- include
        |-- lib

1

用于存放多个Docbook的book（书籍）

后期扩展：可以建更多的book，比如我当前的关于docbook开发笔记，就可以对应新建一个docbook_dev_note的book了。

2

接下来所要写的docbook 5的demo的book

3

用于存放各种格式的输出。

当前暂时为了演示，只建了fo，html，pdf

后期扩展：可以建更多的文件夹，比如htmls，rtf，chm，txt等存放更多的输出格式

4

用于存放fo文件。其可以被fop等工具转换为PDF，RTF等格式

5

用于存放最终生成的html，pdf等格式的文件。这些，是我们所想要的最终的结果。

6

用与存放docbook的xml源码文件。

后期扩展：当单个xml内容太多，可以考虑用xinclude分出多个xml文件，此时多个xml文件，都可以都放在此src文件夹下了。

7

用于存放所有的和Docbook相关的配置文件，包括xsl格式stylesheet文件，以及其他如fop的配置文件等。

后期扩展：其他的，比如，实体定义entity，catalog等等一些内容，也可以放在此config下。

8

此处之所以文件夹叫做docbook-xsl-ns-1.77.1，是由于最新的stylesheet是1.77.1版本的。

其作用是，设置对应的参数，可以控制html，pdf等输出的效果，包括显示效果方面的一些控制参数和输出内容格式组织方面的。

9

此处存放fop的配置。

目前暂时只需要一个fop.xconf文件即可。

10

下载并解压docbook-xsl-ns-1.77.1，然后放到此处即可。

如何下载docbook-xsl-ns-1.77.1参见第 1.2.3 节 “下载docbook-xsl-ns-1.77.1”

11

下载fop 1.0并解压，放到此处即可。

如何下载fop 1.0参见第 1.2.4.1 节 “下载fop-1.0”

12

下载xsltproc及相关文件，并解压，放到此处即可。

如何下载xsltproc及相关文件，参见第 1.2.2 节 “下载windos版本的xsltproc”

顺便贴出后来建立好的docbook环境的文件夹结构的截图：

安装上述介绍，建立好对应的文件夹后，就可以参考下面的步骤，下载相关文件，添加相关配置，编译生成html和pdf，然后最终搭建好docbook环境。

1.2.2. 下载windos版本的xsltproc

在：xsltproc主页 ⇒ 下载页面 ⇒ Libxml ⇒ Igor Zlatkovic提供的Windows下二进制版本的xsltproc中，去下载：

  1. xsltproc主程序

    libxslt-1.1.26.win32.zip

    其中包含我们所需要的xsltproc可执行文件：xsltproc.exe

  2. 运行xsltproc所需要的一些库

    为了在windows下面运行xsltproc，还需要一些其所依赖的库：libxml2，iconv，zlib

    下面依次贴出下载地址和简单的解释：

    • libxml2-2.7.8.win32.zip

      C语言实现的XML解析器。

      其支持N多规范或协议，比如XML，XML-NS，XPath，XPointer，XInclude，UTF-8/UTF-16，XML Catalog，Canonical XML，Relax NG等。

    • iconv-1.9.2.win32.zip

      字符编码转换。比如从UTF-8转换为GB18030，就可以用iconv。

    • zlib-1.2.5.win32.zip

      压缩工具。

下载了这四个文件后，解压，然后都会得到一个包括bin，include，lib三个文件夹。

全部都合并到一起后，放到上述介绍的12中，即可。

把xsltproc的路径添加到PATH环境变量中.  为了可以在windows的命令行cmd中直接输入xsltproc就可以执行，而不需要绝对路径，此处需要把xsltproc所在路径，我此处的的是：E:\DevRoot\docbook\tools\xslt\bin，添加到windows的环境变量PATH中去。

[提示] 如何设置windows环境变量

关于如何添加相应路径到windows的环境变量中，不熟悉的可以参考：

Windows的环境变量

[提示] 更新版本的xsltproc相关的二进制文件

如果想要用更新版本的xsltproc，即相关的各个所依赖的二进制文件，想要下载更新版本的话，

可以去参考：

【已解决】docbook中用xsltproc处理xsl文件时用xsl:import引用本地css，js等文件时，必须加上file:///或file://的前缀才可以

中的"如何组合出来相对比较新的版本的xsltproc"即可。

1.2.3. 下载docbook-xsl-ns-1.77.1

为了将xml源码转换为html，fo等文件的话，需要相应的配置文件，以控制输入的效果和格式，这就需要相应的配置文件。

此处的配置文件，就是xsl格式的stylesheet（样式表）。

docbook官方网站中，有对应的最新的办法的xsl样式表文件，是放在sourceforge上的：最新的docbook-xsl-ns所在的页面

截止当前2012-06-10，最新版本的是1.77.1版本的docbook-xsl-ns，下载下来对应的docbook-xsl-ns-1.77.1.tar.bz2后，解压，放到上面刚建立的10中

1.2.4. 下载fop-1.0并添加fop配置文件

[注意] 如果没有安装java，请先安装java

fop的运行，依赖于java运行环境。

如果你的windows中，还没有安装java，请先安装java运行环境（JRE=java runtime environment）。

关于java的基本知识和如何安装，不了解的请参考：Java

java已经安装好前提下，另外记得确保JAVA_HOME环境变量已经正确设置好了。

比如，我的系统中的是：

JAVA_HOME=D:\Program Files\Java\jre7

1.2.4.1. 下载fop-1.0

从：fop主页 ⇒ Apache™ FOP Version 1.0 ⇒ fop下载页面 ⇒ FOP Distribution mirror中，可以找到第一链接，是官网推荐给你的，然后进去后可以找到binaries文件夹，进去后，下载到fop-1.0-bin.tar.gz，比如我这里得到的地址是：bjtu的fop-1.0-bin.tar.gz

下载解压后，放到上面建的11中即可。

1.2.4.2. 配置FOP的环境变量FOP_HOME

为了更好的让fop自动搜索对应的lib库，需要去设置fop的一个环境变量FOP_HOME。

此处即为，设置对应的环境变量为：

FOP_HOME=E:\DevRoot\docbook\tools\fop-1.0

1.2.4.3. 添加fop配置文件fop.xconf

将原先的11中的conf文件夹中的fop.xconf拷贝一份出来，放到9下

然后打开该文件，找到fop⇒renderers中的fonts部分，然后添加对应的配置，变成：


<fop version="1.0">
    ...
  <renderers>
    <renderer mime="application/pdf">
        ...
      <fonts>
        ...
        
        <!-- new added start -->
         <!-- register all the fonts found in a directory and all of its sub directories (use with care) -->
         <directory recursive="true">file:///c:/windows/fonts/</directory>

         <!-- automatically detect operating system installed fonts -->
         <auto-detect/>
        <!-- new added end -->
      </fonts>

即完成了对应的配置。

[提示] 关于FOP的字体配置

关于fop的更多字体配置方面的内容，可以去参考官网的解释：Custom Fonts

1.2.5. 准备docbook的源码：xml文件

将如下内容：


<?xml version='1.0' encoding="utf-8"?>

<book version="5.0"
    xmlns="http://docbook.org/ns/docbook"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:xl="http://www.w3.org/1999/xlink"
    xml:lang="zh_CN"
    >

<info>
    <title>Docbook5环境搭建演示</title>
    <abstract>
        <para>本文主要介绍了如何在纯Windows的环境下搭建Docbook 5开发环境</para>
    </abstract>
    
    <author><personname><firstname>Crifan</firstname><surname>Li</surname></personname></author>    
    <pubdate>2012-06-05</pubdate>
    <copyright>
        <year>2012</year>
        <holder>Crifan</holder>
        <holder><link xl:href="http://crifan.com" /></holder>
    </copyright>
    <legalnotice>
        <para>本文章遵从：<link xl:href="http://creativecommons.org/licenses/by-nc/2.5/cn/">署名-非商业性使用 2.5 中国大陆(CC BY-NC 2.5)</link></para>
    </legalnotice>
</info>


<chapter><title>第一章的标题</title>
    <para>关于更多的Docbook方面的内容，可以去参考：<link xl:href="http://www.crifan.com/files/doc/docbook/docbook_dev_note/release/html/docbook_dev_note.html">Docbook开发手记</link></para>

    <sect1><title>第一章第一小节的标题</title>
        <para>可以在这里输入第一章第一小节中的内容</para>
        
        <sect2><title>第一章第二小节的标题</title>
            <para></para>
        </sect2>
    </sect1>

    <sect1><title>第一章第二小节标题</title>
        <para></para>
    </sect1>
</chapter>

<chapter><title>第二章</title>
    <para></para>
</chapter>

</book>

存为UTF-8编码的docbook5_demo.xml文件。

用于后期演示使用。

[提示] 如何建立UTF-8编码的文件

可以参考Notepad++的多种编码支持，去用Notepad++建立相应的UTF-8编码的文件。

1.2.6. 从xml生成html

1.2.6.1. 为生成html准备配置文件

将如下内容：

<?xml version='1.0'?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version='1.0'>

<xsl:import href="E:/DevRoot/docbook1/tools/2docbook-xsl-ns-1.77.1/html/docbook.xsl"/>

<!--=====================================​=======================================
font setting
====================================================​=========================-->
<xsl:param name="title.font.family">Microsoft YaHei</xsl:param>
<xsl:param name="body.font.family">Microsoft YaHei</xsl:param>
<xsl:param name="monospace.font.family">Microsoft YaHei</xsl:param>
<xsl:param name="symbol.font.family">Cambria Math</xsl:param>

<!--====================================================​========================
TOC index setting
====================================================​=========================-->
<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="toc.section.depth">8</xsl:param>

</xsl:stylesheet>

1

此处请自行将E:/DevRoot/docbook换为你自己当前的目录。

2

注意，此处的路径中是正斜杠'/'，而不是反斜杠'\'，否则会导致xsltproc无法识别。

存为UTF-8格式的docbook_html.xsl

放到前面建的8中。

1.2.6.2. 将xml转换为html

将xml源码转换为html话，只需要用xsltrpoc一步操作就可以了：

打开windows的命令行cmd，切换到上面建的6下

然后运行如下命令：

xsltproc -o ../output/html/docbook5_demo.html E:\DevRoot\docbook\config\docbook_html.xsl docbook5_demo.xml

即可生成相应的docbook5_demo.html

截图效果如下：

1.2.7. 从xml生成pdf

1.2.7.1. 为生成pdf准备配置文件

将如下内容：

<?xml version='1.0'?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version='1.0'>

<xsl:import href="E:/DevRoot/docbook/tools/docbook-xsl-ns-1.77.1/fo/docbook.xsl"/>

<!--====================================================​========================
font setting
====================================================​=========================-->
<xsl:param name="title.font.family">Microsoft YaHei</xsl:param>
<xsl:param name="body.font.family">Microsoft YaHei</xsl:param>
<xsl:param name="monospace.font.family">Microsoft YaHei</xsl:param>
<xsl:param name="symbol.font.family">Cambria Math</xsl:param>

<!--====================================================​========================
TOC index setting
====================================================​=========================-->
<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="toc.section.depth">8</xsl:param>

<!--====================================================​========================
misc setting
====================================================​=========================-->
<!-- add bookmark and support more type of figure -->
<xsl:param name="fop1.extensions">1</xsl:param>

<!-- no indent for body content -->
<xsl:param name="body.start.indent">0pt</xsl:param>

</xsl:stylesheet>

存为UTF-8格式的docbook_fo.xsl

同理，不要忘了参考上面的1，把E:/DevRoot/docbook换为你自己当前的目录。

把docbook_fo.xsl放到前面建的8中。

1.2.7.2. 将xml转换为fo

同理，在6下

用下列命令去生成fo：

xsltproc -o ../output/fo/docbook5_demo.fo E:\DevRoot\docbook\config\docbook-xsl-ns-1.77.1\docbook_fo.xsl docbook5_demo.xml

相应的屏幕输出为：

E:\DevRoot\docbook\books\docbook5_demo\src>xsltproc -o ../output/fo/docbook5_demo.fo E:\DevRoot\docbook\config\docbook-xsl-ns-1.77.1\docbook_fo.xsl docbook5_demo.xml
Making portrait pages on USletter paper (8.5inx11in)

1.2.7.3. 将fo转换为pdf

再继续执行下面命令：

E:\DevRoot\docbook\tools\fop-1.0\fop.cmd -c E:\DevRoot\docbook\config\fop\fop.xconf -fo ../output/fo/docbook5_demo.fo -pdf ../output/pdf/docbook5_demo.pdf

相应的屏幕输出为：

E:\DevRoot\docbook\books\docbook5_demo\src>E:\DevRoot\docbook\tools\fop-1.0\fop.cmd -c E:\DevRoot\docbook\config\fop\fop.xconf -fo ../output/fo/docbook5_d
 -pdf ../output/pdf/docbook5_demo.pdf
六月 07, 2012 11:28:38 下午 org.apache.fop.apps.FopFactoryConfigurator configure
信息: Default page-height set to: 11in
六月 07, 2012 11:28:38 下午 org.apache.fop.apps.FopFactoryConfigurator configure
信息: Default page-width set to: 8.26in
六月 07, 2012 11:28:41 下午 org.apache.fop.hyphenation.Hyphenator getHyphenationTree
严重: Couldn't find hyphenation pattern zh_cn

如此，就可以正常生成对应的pdf文件了，截图效果如下：

上一页  上一级  下一页
第 1 章 Windows下的Docbook的环境搭建  起始页  1.3. Windows环境下的，基于Cygwin的Docbook开发环境的搭建