在Windows上安装配置Apache FOP

使用Apache FOP将Docbook文档转换成PDF一文中,Easwy介绍了在Debian Linux上使用Apache FOP将Docbook文档转换成PDF文件。本来在那篇文章之后,Easwy想写一篇如何在Windows上配置Apache FOP的文章,不过一直没抽出时间。今天刚好有网友问这个问题,于是教她一步步做下来,把步骤列在下面。

你可以在这里下载到文章中Easwy用到的所有文件:点此下载

  1. 安装Docbook样式表和xsltproc程序

    按照文章一个简单的Docbook 5.0例子,安装Docbook样式表和xsltproc转换程序,并能够成功将Docbook文件转换成html格式。

  2. 安装Apache FOP和Java虚拟机

    Apache Download Mirrors下载Apache FOP,Easwy下载的是FOP 1.0。下载后,将下载的文件解压,Easwy把它解压到C:\docbook\fop-1.0。

    接下来,还要安装Java虚拟机,因为Apache FOP需要Java虚拟机才能运行。到Java网站下载安装即可。

  3. 设置Apache FOP

    我们需要配置Apache FOP进行PDF转换时所用到的字体信息。首先,用下面的命令把字体信息从Windows自带的系统字体中提取出来:

    cd C:\docbook\fop-1.0
    mkdir fonts
    java -cp build\fop.jar;lib\avalon-framework-4.2.0.jar;lib\commons-logging-1.0.4.jar;lib\commons-io-1.3.1.jar;lib\xmlgraphics-commons-1.4.jar org.apache.fop.fonts.apps.TTFReader -ttcname SimSun c:\windows\fonts\simsun.ttc fonts\simsun.xml
    java -cp build\fop.jar;lib\avalon-framework-4.2.0.jar;lib\commons-logging-1.0.4.jar;lib\commons-io-1.3.1.jar;lib\xmlgraphics-commons-1.4.jar org.apache.fop.fonts.apps.TTFReader -ttcname SimHei c:\windows\fonts\simhei.ttf fonts\simhei.xml 

    上面的命令,把C:\Windows\fonts\目录下的宋体和黑体这两种字体信息提取到fonts\simsun.xmlfonts\simhei.xml文件中。

    接下来配置C:\docbook\fop-1.0\conf\fop.xconf,使Apache FOP能够找到这两种字体。首先在文件中找到<renderer mime=”application/pdf”>这一行,然后在此标签中加入关于字体的配置。

            
    <fonts>
      <font metrics-url="fonts/simsun.xml" kerning="yes" embed-url="file:///c:/windows/fonts/simsun.ttc">
        <font-triplet name="SimSun" style="normal" weight="normal"/>
        <font-triplet name="SimSun" style="normal" weight="bold"/>
        <font-triplet name="SimSun" style="italic" weight="normal"/>
        <font-triplet name="SimSun" style="italic" weight="bold"/>
      </font>
    
      <font metrics-url="fonts/simhei.xml" kerning="yes" embed-url="file:///c:/windows/fonts/simhei.ttf">
        <font-triplet name="SimHei" style="normal" weight="normal"/>
        <font-triplet name="SimHei" style="normal" weight="bold"/>
        <font-triplet name="SimHei" style="italic" weight="normal"/>
        <font-triplet name="SimHei" style="italic" weight="bold"/>
      </font>
    
      <directory recursive="true">file:///c:/windows/fonts/</directory>
    
      <auto-detect/>
    </fonts>
             
  4. 配置XLT转换样式表

    接下来,我们要配置XSL转换样式表,让xsltproc在转换Docbook文档时,使用我们指定的中文字体。在下面我给出了一个简单的样式表,假设存为docbook_fo.xsl:

     
    <?xml version='1.0'?>
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      xmlns:exsl="http://exslt.org/common"
      xmlns:fo="http://www.w3.org/1999/XSL/Format"
      xmlns:ng="http://docbook.org/docbook-ng"
      xmlns:db="http://docbook.org/ns/docbook"
      exclude-result-prefixes="db ng exsl"
      version='1.0'>
    
      <xsl:import href="C:/docbook/docbook-xsl-1.74.3/fo/docbook.xsl"/>
      <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:stylesheet>
             

    在这个转换样式表里,首先导入了Docbook的FO样式表,然后重新设置了其中的字体参数,改成我们所要的字体名称。需要注意的是,这里的字体名字需要和fop.xconf中设置的font-triplet中的名字完全一致。

  5. 输出PDF文件

    完成上述配置后,就可以进行PDF文件的转换了。把下面的文件保存为example.xml

            
    <?xml version='1.0' encoding="utf-8"?>
    
    <article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="zh-CN"
      xmlns:xlink='http://www.w3.org/1999/xlink'>
      <articleinfo>
        <title>我的第一篇Docbook 5.0文档</title>
        <author>
          <firstname>Easwy</firstname>
    
          <surname>Yang</surname>
        </author>
      </articleinfo> 
    
      <section>
        <title>文档介绍</title>
    
        <para>
          这是我的第一篇Docbook 5.0文档,欢迎你来到<link xlink:href='http://easwy.com/blog/'>Easwy的博客</link>。
        </para>
      </section>
    </article> 
             

    然后输入下面的命令将其转换成PDF:

    xsltproc -o example.fo c:\docbook\fop-1.0\conf\docbook_fo.xsl example.xml
    fop -c c:\docbook\fop-1.0\conf\fop.xconf example.fo -pdf example.pdf 

更多内容,请阅读易水博客上的其它文章。

参考文档

原创文章,请阅读页脚的许可方式,转载请注明:转载自易水博客 [ http://easwy.com/blog/ ]

本文链接地址: http://easwy.com/blog/archives/install-apache-fop-on-windows/

文章的脚注信息由WordPress的wp-posturl插件自动生成

使用FOP转换Docbook到PDF时遇到的错误及解决 (一)

本文记录了我在配置使用Apache FOP时遇到的错误以及解决方法。一方面是做个记录,将来再遇到此类问题时可以查询;另一方面也希望对其它遇到同样问题的人有所帮助。

  1. 问题:fo:inline错误

    解决

    转换vim使用进阶到PDF时,遇到了下面这样一个问题(完整错误信息见fo:inline错误):

    javax.xml.transform.TransformerException: org.apache.fop.fo.ValidationException: file:/home/easwy/tmp/advancedvim/pdf/vim_advanced_usage.fo:173:59: Error(173/59): fo:inline is not a valid child element of fo:flow.
    	at org.apache.fop.cli.InputHandler.transformTo(InputHandler.java:168)
    	at org.apache.fop.cli.InputHandler.renderTo(InputHandler.java:115)
    	at org.apache.fop.cli.Main.startFOP(Main.java:166)
    	at org.apache.fop.cli.Main.main(Main.java:197)
          

    看错误提示,是说fo:inline不是fo:flow元素的有效子结点。在网上搜了一下没找到有用的信息。仔细检查出错的位置,终于发现错误的原因,错误出在下面这个语句:

    
    <emphasis role='bold'> [文件浏览] </emphasis>
    <para>
      ...
    </para>
     

    在上面的emphasis元素是一个inline元素,对于这种inline元素来讲,一定要包含在某个块元素中。而上面的语句中,emphasis不属于任何一个para,所以出现上述错误。

    把上面的语句改成下面的形式,错误消除:

    
    <para><emphasis role='bold'> [文件浏览] </emphasis></para>
    
    <para>
      ...
    </para>
     
  2. 问题:转换PNG插图时出现空指针异常

    解决

    还是在转换vim使用进阶时,出现下面的空指针异常(详细错误信息见PNG插件导致的空指针异常):

    严重: Exception
    java.lang.NullPointerException
    	at org.apache.fop.cli.InputHandler.transformTo(InputHandler.java:168)
    	at org.apache.fop.cli.InputHandler.renderTo(InputHandler.java:115)
    	at org.apache.fop.cli.Main.startFOP(Main.java:166)
            at org.apache.fop.cli.Main.main(Main.java:197) 
          

    经排除,这个异常是在转换下面的语句时发生的:

    
      <informalfigure>
        <mediaobject>
          <alt>在vim中使用gdb调试 - vimgdb</alt>
          <imageobject>
            <imagedata fileref='http://easwy.com/blog/uploads/2009/03/vimgdb2-300x216.png' align='center'/>
    
          </imageobject>
        </mediaobject>
        <caption align='center'><link xlink:href='http://easwy.com/blog/uploads/2009/03/vimgdb2.png' xlink:show='new'>点击查看大图</link></caption>
      </informalfigure>
       

    如果把imagedata中文件的URL换成JPG格式的图像文件,则转换正常。一旦使用PNG格式的文件,就会出现上面的空指针异常提示。在网上也没找到解决办法,查看了一下自己的FOP版本:

    FOP Version 0.94      
        

    猜想可能这是旧版本的BUG,于是下载了最新的FOP trunk版本,进行编译:

    
    svn co http://svn.apache.org/repos/asf/xmlgraphics/fop/trunk/
    ant all 

    使用这个版本再进行转换,果然错误消除。

  3. 问题:zh_cn hyphenation的问题

    解决

    在我的docbook文档中,都加有xml:lang=’zh-CN’这样的标志,指明本文档的语言是中文简体。

    但每次进行PDF文件转换时,都有下面的提示:

    严重: Couldn't find hyphenation pattern zh_cn
          

    在网上搜了一下,感觉这应该不是一个问题。对其它西文语言如英语、法语等,它们以单词为单位,单词之间采用空格隔开,如果单词太长需要换行时,就要在合适的地方加上一个连字符”-“。但对中文来讲,根本没有这个需要。所以这个错误提示忽略即可。

    不过,如果提示你找不到其它语言的hyphenation,例如找不到en_US的hyphenation,就需要到Objects For Formatting Objects(OFFO)去下载,出于版权方面的考虑,hyphenation缺省不再包含在FOP中了。

原创文章,请阅读页脚的许可方式,转载请注明:转载自易水博客 [ http://easwy.com/blog/ ]

本文链接地址: http://easwy.com/blog/archives/fop-errors-and-solution/

文章的脚注信息由WordPress的wp-posturl插件自动生成

使用Apache FOP将Docbook文档转换成PDF

在写完一个简单的Docbook 5.0例子后,刚好有网友希望我把2009以前vim使用进阶系列文章转换成PDF文档。于是就开始搭建FOP的环境,没想到花费了两天时间,才总算把Apache FOP转换Docbook文档到PDF的环境搭建起来,期间走了很多弯路。

本文简单介绍一下在Debian Lenny上搭建FOP转换环境的过程。下一篇文章介绍一下如何在Windows上搭建FOP环境。另外还会再写一篇文章,列出我在搭建环境过程中遇到的问题以及解决方法,希望对遇到类似问题的人有帮助。

按下面的步骤搭建环境,你可以在这里下载到Easwy的FOP配置及示例文件。

  1. 安装相关软件

    在Debian上安装软件是非常容易的事,只要下面一条命令,就可以把Docbook相关的软件全部安装完成。

    aptitude install docbook-xml docbook-xsl xsltproc fop 

    上面的命令会把它们所依赖的软件包也一并装好。安装完成后,主要软件所在的目录如下:

    • docbook-xsl – /usr/share/xml/docbook/stylesheet/nwalsh/,这是Docbook的XSL转换样式表,Lenny中带的是1.73.2版本,最新版本为1.74.3。不过我觉得Lenny中的已经够用了
    • xsltproc – /usr/bin/xsltproc,这个是Docbook转换工具,用C语言写的,转换速度非常快
    • fop – /usr/bin/fop,Apache的FOP转换工具,主要用来把xsltproc输出的fo格式文件,转换成PDF文件,Lenny中带的是0.94,最新版本是0.95
  2. 设置FOP

    首先创建一个目录来存放FOP的配置信息,在这里我创设使用/etc/fop/目录。

    FOP已经能够很好的支持中文,但是如果想让FOP使用Type1类型字体以及TrueType类型字体的话,还需要为这些字体生成Metrics文件,并在FOP的配置文件中进行设置。

    在Debian Lenny中提供了一个名为/usr/bin/fop-ttfreader的脚本,它其实只是对org.apache.fop.fonts.apps.TTFReader的封装,关于org.apache.fop.fonts.apps.TTFReader程序的用法我在下篇文章里讲,你也可以参考文尾的第二篇参考文档。

    在Debian Lenny中配置中文一文中,我已经把Windows下的宋体拷贝到了Lenny中,要想FOP把这个字体嵌入到PDF文档中,需要使用/usr/bin/fop-ttfreader来生成TTF字体的Metrics文件。

    我的字体文件为/usr/local/share/fonts/msfonts/simsun.ttc,先用下面的命令看看这个字体集合中有几个字体:

    /usr/bin/fop-ttfreader /usr/local/share/fonts/msfonts/simsun.ttc /etc/fop/simsun.xml
    TTF Reader for Apache FOP 0.94
    
    Parsing font...
    Reading /usr/local/share/fonts/msfonts/simsun.ttc...
    This is a TrueType collection file with 3 fonts
    Containing the following fonts: 
    SimSun
    NSimSun
    SimSun-PUA
    Error while building XML font metrics file.
    java.lang.IllegalArgumentException: For TrueType collection you must specify which font to select (-ttcname) 

    忽略上面显示的异常,我们的目的只是看这个字体集中有几种字体,从上面的输出中可以看到有三个字体:SimSunNSimSunSimSun-PUA

    好,接下来我们为SimSun字体生成一个Metrics文件,在刚才那条命令中加上参数-ttcname SimSun参数(注意,字体名区分大小写),再执行一次,这一次输出如下:

    /usr/bin/fop-ttfreader -ttcname SimSun /usr/local/share/fonts/msfonts/simsun.ttc /etc/fop/simsun.xml
    TTF Reader for Apache FOP 0.94
    
    Parsing font...
    Reading /usr/local/share/fonts/msfonts/simsun.ttc...
    This is a TrueType collection file with 3 fonts
    Containing the following fonts: 
    SimSun <-- selected
    NSimSun
    SimSun-PUA
    Font Family: SimSun
    Creating xml font file...
    Creating CID encoded metrics...
    Writing xml font file /etc/simsun.xml...
    This font contains no embedding license restrictions.
    
    XML font metrics file successfully created.
          

    这一次执行成功了,生成的Metrics文件为/etc/fop/simsun.xml。你可以继续用这条命令为其它你想用的TTF或Type1字体生成Metrics文件。

    接下来设置FOP,我是直接把FOP 0.95自带的缺省配置文件拷贝了一份到/etc/fop/fop.xconf,然后再进行修改(我下载了一个FOP 0.95,不过只用了它的配置文件 ^_^):

    首先在文件中找到<renderer mime=”application/pdf”>这一行,然后在此标签中加入关于字体的配置。在FOP 0.94中已经支持对字体的自动检测,不过如果你的字体不在标准字体目录里,还是需要指明字体的目录。例如,我在配置文件中加入以下设置:

            
          <fonts>
            <font metrics-url="file:///etc/fop/simsun.xml" kerning="yes" embed-url="file:///usr/local/share/fonts/msfonts/simsun.ttc">
              <font-triplet name="SimSun" style="normal" weight="normal"/>
              <font-triplet name="SimSun" style="normal" weight="bold"/>
    
              <font-triplet name="SimSun" style="italic" weight="normal"/>
              <font-triplet name="SimSun" style="italic" weight="bold"/>
            </font>
    
            <font metrics-url="file:///etc/fop/simhei.xml" kerning="yes" embed-url="file:///usr/local/share/fonts/msfonts/simhei.ttf">
              <font-triplet name="SimHei" style="normal" weight="normal"/>
              <font-triplet name="SimHei" style="normal" weight="bold"/>
    
              <font-triplet name="SimHei" style="italic" weight="normal"/>
              <font-triplet name="SimHei" style="italic" weight="bold"/>
            </font>
    
            <directory recursive="true">/usr/share/fonts/</directory>
            <auto-detect/> 
          </fonts>
    
             
          

    上面的配置加入了SimSun和SimHei两种字体,并加入字体目录/usr/share/fonts//usr/local/share/fonts/,同时打开了auto-detect。FOP只在第一次运行时扫描字体,然后为之生成缓存,以后就不必再扫描了。

  3. 配置XSL转换样式表

    接下来,我们要配置XSL转换样式表,让xsltproc在转换Docbook文档时,使用我们指定的中文字体。在下面我给出了一个简单的样式表,假设存为docbook_fo.xsl:

     
    <?xml version='1.0'?>
    
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                    xmlns:exsl="http://exslt.org/common"
                    xmlns:fo="http://www.w3.org/1999/XSL/Format"
                    xmlns:ng="http://docbook.org/docbook-ng"
                    xmlns:db="http://docbook.org/ns/docbook"
                    exclude-result-prefixes="db ng exsl"
                    version='1.0'>
    
    <xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl"/>
    <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:stylesheet>
             

    在这个转换样式表里,首先导入了Docbook的FO样式表,然后重新设置了其中的字体参数,改成我们所要的字体名称。需要注意的是,这里的字体名字需要和/etc/fop/fop.xconf中设置的font-triplet中的名字完全一致。

    我之所以配置两天才配好FOP,就是因为在这里犯了个错误。我最初的docbook_fo.xsl中,在导入FO样式表时,使用的是<xsl:include …>,它和<xsl:import …>的区别在于,使用import导入时,先使用本文件中参数设置,当本文件中未对参数进行设置时,才使用所导入文件中的设置;但使用include导入却不是这样。所以,即使我在docbook_fo.xsl中对输出字体进行了重新设置,但实际上我的修改未生效,xsltproc输出的.fo文件中字体用的根本不是我所指定的。最终的结果就是文章中的中文,都被显示成了###。

  4. 输出PDF文件

    上面的配置完成以后,就可以输出PDF文件了。只需要使用下面两条命令即可:

    /usr/bin/xsltproc -o render_docbook_xml_to_pdf_by_apache_fop.fo docbook_fo.xsl render_docbook_xml_to_pdf_by_apache_fop.xml
    /usr/bin/fop -c /etc/fop/fop.xconf render_docbook_xml_to_pdf_by_apache_fop.fo -pdf render_docbook_xml_to_pdf_by_apache_fop.pdf

    上面两条命令会有大量的错误提示,暂时不管它,去看看输出的pdf文档吧,尽管还有诸多不满意,不过总算能输出出来了。接下来需要解决的问题还很多,比如如何分别为中英文指定字体族、如何更好的断字等,留待以后慢慢解决。

参考文档

原创文章,请阅读页脚的许可方式,转载请注明:转载自易水博客 [ http://easwy.com/blog/ ]

本文链接地址: http://easwy.com/blog/archives/render_docbook_xml_to_pdf_by_apache_fop/

文章的脚注信息由WordPress的wp-posturl插件自动生成

一个简单的Docbook 5.0例子

我使用Docbook写文档大约才一两个月的时间,但关注Docbook已经很久了,在网上也阅读了很多中文及英文的Docbook文档。一直没用Docbook的主要原因是Docbook 4.2的编译环境配置看起来很繁琐。我曾经尝试配置过一次,但看到一大堆catalog配置、SGML配置、OpenJade配置,最终放弃了。

直到有一天,我看到benr写的Playing With DocBook 5.0,才第一次真正书写Docbook文档。Docbook 5.0不再使用旧的SGML DTD,转而使用XML,编译环境配置简单多了。

下面我先介绍Windows下如何搭建Docbook 5.0编译环境,然后再以一个简单的Docbook 5.0文档为例,讲一下如何把Docbook文档转换成其它格式。

[ Windows下Docbook编译环境的搭建 ]

  1. 下载Docbook XSL样式表

    首先下载Docbook XSL转换样式表。我们只需要下载docbook-xsl-ns即可,目前的最新版本是1.74.3。下载后,把它解压到一个目录中,我这里假设解压到C:\docbook目录,也就是说,Docbook XSL所在的目录是: C:\docbook\docbook-xsl-ns-1.74.3\

    Docbook介绍一文中我讲过Docbook是”内容与格式分离”的,我们写Docbook文档时只关注文档的内容,而Docbook如何转换成其它文档类型,则由Docbook XSL转换样式表来定义。我们最常用的是转换到HTML格式的样式表,以及转换到FO格式的样式表。

  2. 下载xsltproc转换程序

    接下来,需要下载XML语言转换工具。我喜欢用的转换工具是xsltproc,这是一个由C语言写成的XML转换工具,它的特点是转换速度很快,并且同时支持Windows和Linux。除了这个转换工具外,还有很多Java写的转换工具,例如Saxon, Xalan

    我们到这里下载Windows版本的xsltproc,需要下载下面几个包:

    • iconv-1.9.2.win32.zip – 编码转换工具
    • zlib-1.2.3.win32.zip – 压缩工具
    • libxslt-1.1.24.win32.zip – XSL和EXSL转换工具,xsltproc程序就在此包中
    • libxml2-2.7.3.win32.zip – XML解析工具和处理工具,同时提供了验证工具xmllint和xmlcatalog

    下载后,把这些包解压到同一个目录里,假设解压到C:\docbook\xsltproc目录,解压后,你可以看到在C:\docbook\xsltproc\下多了三个目录:bin,include和lib。现在需要在环境变量PATH中增加C:\docbook\xsltproc\bin,设置后,再打开一个DOS窗口,可以直接输入xsltproc命令,不需要输入使用全路径了。

  3. 安装FOP

    安装了上面的两个工具,你就可以把Docbook文档转换成HTML格式了。如果你需要把Docbook文档转换成PDF格式,还需要安装把XSL-FO格式转换为PDF格式的转换工具,Apache FOP是一个不错的选择。不过我现在没有这方面的需求,暂时没有安装。据说配置Apache FOP支持中文比较繁琐,改天我试过再把经过写出来。(2009/04/11更新,关于Apache FOP的配置,参见文章使用Apache FOP将Docbook文档转换成PDF (一)

现在,Docbook的编译环境就建好了。相比Docbook 4.2,编译环境的搭建容易了很多,你不必再去配置catalog这些东西,因为Docbook 5.0已经不再需要文档类型定义了。

接下来,我们写一个简单的Docbook文档。

[ 编写Docbook文档 ]

你可以在这里下载本例中用到的文件,包括docbook.xml、docbook_easwy.xsl和Easwy的Makefile。

下面是一个简单的Docbook 5.0文档,把这段内容保存一下,例如,存为文件docbook.xml。

<?xml version='1.0' encoding="utf-8"?>
<article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="zh-CN"
  xmlns:xlink='http://www.w3.org/1999/xlink'>
  <articleinfo>
    <title>我的第一篇Docbook 5.0文档</title>
    <author>
      <firstname>Easwy</firstname>

      <surname>Yang</surname>
    </author>
  </articleinfo> 
                  
  <section>   
    <title>文档介绍</title>

    <para>
      这是我的第一篇Docbook 5.0文档,欢迎你来到<link xlink:href='http://easwy.com/blog/'>Easwy的博客</link>。
    </para>
  </section>
</article> 

[ 将文档转换成HTML格式 ]

在转换之前,要先把输出编码设置为UTF-8。docbook-xsl-ns的缺省输出编码是ISO-8859-1,但对于中文字符,我们应该把输出编码设置为UTF-8,否则输出的文件会显示为乱码。

更改输出编码很简单,你可以直接修改你的C:\docbook\docbook-xsl-ns-1.74.3\html\docbook.xsl文件,在文件中找到

   <xsl:output method="html"
            encoding="ISO-8859-1"
            indent="no"/>     

把它改成

   <xsl:output method="html"
            encoding="UTF-8"
            indent="no"/>     

我一般是另外写一个xsl文件,在这个文件中包含标准的docbook-xsl,然后重新定义自己的编码为UTF-8。把下面的文件保存为docbook_easwy.xsl:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version='1.0'>
<xsl:include href="C:/docbook/docbook-xsl-ns-1.74.3/html/docbook.xsl"/>
<xsl:output method="html"
            encoding="UTF-8"
            indent="no"/>
</xsl:stylesheet> 

接下来,我们把上面的Docbook文档转换成HTML格式,使用下面的命令:

xsltproc -o docbook.html docbook_easwy.xsl docbook.xml 

如果你看到类似下面的提示,那么你的xsl不是docbook-xsl-ns,而是docbook-xsl。如果不想下载docbook-xsl-ns的话,忽略告警即可,这些告警并不影响使用。

1: Note: namesp. cut : stripped namespace before processing 我的第一篇Docbook 5.0文档

2: WARNING: cannot add @xml:base to node set root element. Relative paths may not work.

3: Note: namesp. cut : processing stripped document 我的第一篇Docbook 5.0文档

如果嫌每次输入转换命令太麻烦,可以把上面的命令保存为一个批处理文件。我在Windows里安装了Cygwin (参考这篇文章安装cygwin),所以一般用Makefile来转换Docbook源文件。我的Makefile内容如下:

# Docbook Makefile
# Easwy Yang

XSLFILE=docbook_easwy.xsl

XML_FILE=$(wildcard *.xml)
HTML_FILE=$(XML_FILE:.xml=.html)

.PHONY: html clean

html : $(HTML_FILE)

%.html : %.xml
	xsltproc -o $(@F) $(XSLFILE) $<

clean:
	rm *.html 

现在,我在vim里可以直接使用:make命令转换我的Docbook源文档了。

原创文章,请阅读页脚的许可方式,转载请注明:转载自易水博客 [ http://easwy.com/blog/ ]

本文链接地址: http://easwy.com/blog/archives/a-simple-docbook-5-example/

文章的脚注信息由WordPress的wp-posturl插件自动生成

Docbook介绍

本文主要介绍一下Docbook是什么,下一篇将给出一个最简单的Docbook文档做为例子。

Docbook提供了整个书写结构化文档的体系,它使用SGML/XML定义了一系列文档元素,并可以利用工具把原始的文档源文件转换成各种文档格式。它最适合用来书写计算机文档、论文。很多开源软件项目都使用Docbook来写自己的文档。在我看来,使用Docbook写文档的好处有以下几点:

  • 内容与格式分离

    我们用Word写文档时,除了书写文档内容之外,还要经常对文档的样式进行排版。我们都知道,排版很是费时费力,还经常容易出错。

    而使用Docbook书写文档,你只需要专注于文档的内容。文章的内容和格式是分离的。Docbook定义了诸如章节(chapter)、段落(para)、表格(table)这些文档元素,但如何显示这些元素,则由样式表(XSL)来控制,你不必在文档中嵌入排版信息。

    这也意味着,你不能用”所见即所得”的方式来编辑你的文档了。不过,你很快就会喜欢上内容和格式分离的,因为这不仅节省了排版的时间、也使文档样式更为统一。另外,使用程序自动处理文档也变得更加容易了。

  • 多种文件格式输出

    使用Docbook书写文档,你只需要书写文档一次,就能够以多种文件格式输出。有很多免费的工具可以将Docbook文档转换成HTML、PDF,以及其它各种文件格式。

  • 便于版本管理

    这也是我选择Docbook的主要原因之一。因为Docbook的文档源文件是文本文件,因此可以方便的使用cvs, subversion, git等版本管理工具进行版本管理。

    在多人协作编写文档时,如果没有版本管理的功能,你很难知道别人对文档做了哪些修改,更别说回溯文档的历史。在公司里,一般可以通过约定规则的方法来控制冲突,即事先约定好,你只允许改哪几章,他只能改哪几章。但对开源世界的”大集市”开发模式来说,无法通过约定的方法来避免冲突,因此对文档的版本管理就显得非常重要。这就是为什么很多开源项目的文档都使用Docbook的原因。

  • 方便阅读

    阅读word文档,需要你安装了Macrosoft Word;阅读PDF文档,需要安装PDF阅读器。设想十年以后,当Word不再维护,而你又需要阅读一个十年前使用Word写就的文档,会怎么样?是的,你读不了,因为Word文档是二进制格式的,你必须使用特殊的程序才能阅读、编辑。

    但Docbook文档就不同了,你只要使用一个再普通不过的文本编辑器,就可以阅读、编辑Docbook的文档,因为它只是一个普通的文本文件。

  • 多平台支持

    在Windows上你可以使用Word来察看、编辑文档(不管用的是正版,或是盗版),但在Linux下怎么看Word文档呢?谢天谢地,现在有了Open Office。在以前,Linux下是无法察看Word文档的,因为它是一个二进制文件。

    Docbook是文本文档,因此,无论你是在windows下还是Linux下,都可以阅读、书写文档。而Docbook的转换工具大多由Java编写,也支持跨平台运行。这样一来,你可以在多种操作系统平台下使用统一的方式来管理你的文档了。

  • 多语言支持

    Docbook使用UTF-8字符集,因此,在文档中可以使用多国语言的字符集。这对国际化合作的项目来说很重要。

正因为Docbook有这么多的优点,所以我才将我的vim使用进阶系列文章使用Docbook重新整理了一遍(因为之前的Word文档因意外被损坏,无法打开)。今后我的文档也都会使用Docbook书写。就连博客上的文章,大部分也是先用Docbook书写,然后转换成HTML再发上来的。

如果你也对Docbook写文档有兴趣,可以在网上搜索一下相关的文章。我会陆续写一些Docbook的文章发表在Easwy的博客,欢迎交流。

原创文章,请阅读页脚的许可方式,转载请注明:转载自易水博客 [ http://easwy.com/blog/ ]

本文链接地址: http://easwy.com/blog/archives/docbook_intro/

文章的脚注信息由WordPress的wp-posturl插件自动生成

xlink:href不能生成html超链接

刚开始使用Docbook 5.0,遇到一个很奇怪的问题,当我使用下面的代码时:

<link xmlns:xlink=’http://www.w3.org/1999/xlink/’
xlink:href=’http://easwy.com/blog/’>Easwy的博客</link>

然后转换成html格式,超链接总是丢失。为了解决这个问题,我进行了很多尝试。

刚开始怀疑Windows版本的xsltproc有Bug,于是换到Linux下,再进行转换,情况还是一样。接下来,把xsltproc换成其它的转换工具,但换成Saxon后,生成的html文件中依然没有超链接信息。

看来应该是自己Docbook文档写的有问题,于是尝试为xlink增加各种属性,先后试了xlink:type=’simple’,xlink:show=’new’,xlink:lable=’easwy.com’,可无论怎么改,最后的效果完全相同。于是我又尝试使用Docbook 4.4中的ulink来表示链接,这次一切正常。按DocBook V5.0 The Transition Guide的说法,应该”link xlink:href”在Docbook 5.0里已经取代了ulink,为什么不行呢?

在网上Google了很久,都没发现其它人出现过同样的问题,看来问题还是出在自己的Docbook文档中。无意在看一个网页时,发现它的xlink的namespace的URL写做

xmlns:xlink=’http://www.w3.org/1999/xlink’

而不是我的

xmlns:xlink=’http://www.w3.org/1999/xlink/

注意到区别了吗?我的URL在结尾处多了一个”/”。

当我把xlink的URL改成不带结尾”/”的后,生成的html文件终于包含超链接了。
原来,只要”xmlns:xlink”中的链接地址不正确,就不能生成超链接。

问题是如此简单!不知道还有没有人犯和我同样的错误。

原创文章,请阅读页脚的许可方式,转载请注明:转载自易水博客 [ http://easwy.com/blog/ ]

本文链接地址: http://easwy.com/blog/archives/xlink-href-can-not-generate-hyperlink/

文章的脚注信息由WordPress的wp-posturl插件自动生成