Hack JBoss JDocBook Plugin

我上个月已经在javaeye建立了 （号称国内最大的Java 社区），但几乎很少人对其感兴趣，加入圈子的人就更少了。作为一个技术人员，我感觉了一个没有来由的悲哀。在国外，不管是开源项目还是商业项目，已经习惯了使用DocBook来写文档，在国内大多数人可能还是热衷微软的Word。
前两天刚刚在 Google Code 上共享了我的DocBook 构建工具 ， 并在javaeye的灌水论坛了发布了这一消息，我从来没有指望引起太多的关注，事实上也是如此。不过还好，有人在用DocBook。其中一个用户抱怨 JBoss JDocBook Plugin无法正确的处理中文PDF。我曾经使用多个Docbook构建工具，由于中文支持或是配置缺少灵活性，最后几乎都放弃了。
今天从JBoss的 subversion 库取出了JBoss JDocBook Plugin 2.1.2 的源代码。

[hantsy@localhost app]$ svn co maven-jdocbook-plugin-2.1.2

JDocBook插件中可以配置很多参数，这些参数在 org.jboss.maven.plugins.jdocbook.AbstractDocBookMojo 中以类的属性形式存在。
但遗憾的是，没有看到配置FOP(JDocBook使用Apache FOP生成PDF)的属性，默认情况下，FOP肯定不能处理中文字体的PDF输出。
找到PDF处理的相关类文件。
在 org.jboss.jdocbook.render.impl 有几个核心处理，PDFRender是专门用来生成PDF， BasicRender用来转换其它格式的文件。
RenderFactory是一个工厂类，根据要生成的 格式要创建相应的Render。
真正的生成动作是在 org.jboss.maven.plugins.jdocbook.GenerateMojo中进行。

这里我们很容易发现，RenderFactory，PDFRender中注入了一个Options类。而在GenerateMojo中也使用了Options，Options 对应于了JDocBook插件一个配置属性options。

看到我便很快找到一个思路。

在Options追加一个属性，指定FOP自定义配置文件的位置。

public class Options{
...
private String userConfig;

public String getUserConfig() {
return userConfig;
}

public void setUserConfig(String userConfig) {
this.userConfig = userConfig;
}
...
}

在PDFRender 中内部类ResultImpl的代码

FopFactory fopFactory = FopFactory.newInstance();

下面添加一行代码：

fopFactory.setUserConfig(options.getUserConfig());

现在看来，FOP通过FopFactory设置了用户配置文件，接下来应该和之前我所使用 ANT 处理方法是一致的。

现在来验证一下。

这里以JBoss Cache Core 的文档为例说明（我的文档来源于javaeye社区，你可以从 获得其DocBook源代码）。

[hantsy@localhost app]$ svn co jboss-cache-core-doc-zh-cn

下面是pom.xml文件的一部分（这里仅测试User Guide部分）。

User Guide




package





org.jboss.maven.plugins
maven-jdocbook-plugin
2.1.2.patched［1］
true


org.jboss
jbossorg-docbook-xslt
1.1.0


org.jboss
jbossorg-jdocbook-style
1.1.0
jdocbook-style


org.apache.xmlgraphics
fop
0.95［2］

［3］
avalon-framework
avalon-framework
4.1.5


avalon-framework
avalon-framework-impl
4.1.5




userguide_zh_CN
package

resources
generate


master.xml
${basedir}/src/main/docbook/userguide/zh_CN

${basedir}/src/main/docbook/images


${basedir}/src/main/docbook/css

${basedir}/target/docbook/userguide_zh_CN

［4］
pdf
    classpath:/xslt/org/jboss/pdf.xsl
    userguide_zh_CN.pdf


    html
    classpath:/xslt/org/jboss/xhtml.xsl
    index.html


    html_single
    classpath:/xslt/org/jboss/xhtml-single.xsl
    index.html



false
src/main/resources/fop.xconf［5］

[1]我将刚刚修改过的JBoss DocBook Plugin重新打包，版本号命名为2.1.2.pachted，以示区别。

[2]我打算使用最新的FOP。

[3]添加avalon框架的依赖。

[4]在源文件中注释掉了，现在把它打开。

[5]指定FOP的配置文件位置，这里使用我以前在Ant 环境中久经使用配置文件，并把放到此项目目录中。

现在万事俱备了，现在只要在xslt样式文件中加入中文字体配置就行了。

找到 jbossorg-docbook-xslt 这个依赖的 jar文件（位于~/.m2/repository/org/jboss/jbossorg-docbook-xslt/1.1.0），解压jar文件。

打开/xslt/org/jboss/pdf.xsl 找到以下 代码段：

    


    


    


    

替换成：

'SimSun'
'SimHei'
'SimKai'
'SimSun'

当然也可以上面定义的模板(pickfont-mono, pickfont-sans)，这也是理想的方式，能够兼顾各种语言。

注意，FOP 0.95 还不支持字体簇，你无法使用中英文字体混合的字体族。如'Times New Roman', 'SimSun'，最新FOP中已经支持，但效果仍然不是很理想。参见：使用Apache FOP将Docbook转换成PDF文档。

现在可以开始生成PDF了。

执行 mvn package -Puser\ Guide ，就可以得到一份中文pdf了。

附上生成了JBoss Cache Core User Guide 的pdf文件和我的fop.xconf配置文件（使用时根据自己的环境，需要自行修改字体路径）。

需要说明的，fop生成truetype字体的metrics文件，请使用当前使用fop版本来生成。我发现它与最新的fop生成的文件有少量不兼容。另外，字体生成的 cache文件也存在不兼容的现象，运行mvn之前清除 ~/.fop/fop-fonts.cache文件。