【背景】
想要用Docbook输出尽可能多的格式。
目前已经可以输出HTML，HTMLs，PDF，Plain Text，CHM，RTF等格式了。
现在发现docbook-xsl-ns-1.76.1有个webhelp，所以想要看看是个啥东东，可以的话，也生成一个试试。
【折腾过程】
1.找到了：Using DocBook to Generate WebHelp，通过其截图：
然后又参考 webhelp wiki中的例子：
Rackspace Cloud Files API documentation
然后算是明白了，就类似于在线的CHM，其类似的效果和系统，之前就见过了，比如arm官网的在线文档系统等。
搞清楚了webhelp是啥，然后就可以去折腾如果将docbook输出为webhelp了。
2.继续参考上面的：Using DocBook to Generate WebHelp，去试试xsltproc。
然后：
（1）将webhelp.css从
CLi@PC-CLI-1 ~/develop/docbook/books/VBR/VBR/src $ XML_CATALOG_FILES="/home/CLi/develop/docbook/config/catalog/catalog.xml" XML_DEBUG_CATALOG=1 xsltproc.exe --xinclude -o ../output/webhelp/MPEG_VBR.html docbook_webhelp_crl.xsl MPEG_VBR.xml Resolve: sysID docbook_webhelp_crl.xsl -2147483592 Parsing catalog /home/CLi/develop/docbook/config/catalog/catalog.xml /home/CLi/develop/docbook/config/catalog/catalog.xml added to file hash Resolve URI docbook_webhelp_crl.xsl Found URI match docbook_webhelp_crl.xsl Resolve: pubID crl.ent sysID null Found public match crl.ent language: en No "zh_cn" localization of "txt_filesfound" exists; using "en". No "zh_cn" localization of "txt_enter_at_least_1_char" exists; using "en". No "zh_cn" localization of "txt_browser_not_supported" exists; using "en". No "zh_cn" localization of "txt_please_wait" exists; using "en". No "zh_cn" localization of "txt_results_for" exists; using "en". No "zh_cn" localization of "HighlightButton" exists; using "en". No "zh_cn" localization of "Search" exists; using "en". No "zh_cn" localization of "Search" exists; using "en". ..... Writing docs/content/index.html for book Writing docs/index.html Catalogs cleanup Free catalog entry crl.ent Free catalog entry /home/CLi/develop/docbook/tools/docbook-xsl-ns-1.76.1/ Free catalog entry docbook_html.xsl Free catalog entry docbook_fo.xsl Free catalog entry /home/CLi/develop/docbook/config/docbook-xsl-ns-1.76.1/ Free catalog entry docbook_html_crl.xsl Free catalog entry chunk_html_crl.xsl Free catalog entry docbook_htmlhelp_crl.xsl Free catalog entry docbook_webhelp_crl.xsl Free catalog entry docbook_fo_crl.xsl Free catalog entry /home/CLi/develop/docbook/config/catalog/catalog.xml Free catalog entry
【后记 2012-08-25】
后来还是打算，参考之前的官网的教程Generating webhelp output去用saxon编译webhelp，下面记录过程：
1.去saxon官网下载免费的Saxon-HE版本的安装文件SaxonHE9-4-0-4N-setup.exe，然后安装。
2.去cmd中确定当前的java满足条件：
C:\Users\Administrator>java -version java version "1.7.0_01" Java(TM) SE Runtime Environment (build 1.7.0_01-b08) Java HotSpot(TM) Client VM (build 21.1-b02, mixed mode, sharing)
3.然后再去Ant官网下载了apache-ant-1.8.4-bin.tar.bz2，解压，放到某个位置，再添加相关的环境变量：
ANT_HOME=E:\dev_install_root\apache_ant\apache-ant-1.8.4
再把%ANT_HOME%\bin添加到环境变量PATH中。
4.去重新开个cmd，验证一下应该可以找到ant了：
C:\Users\Administrator>ant --version Unable to locate tools.jar. Expected to find it in D:\Program Files\Java\jre7\lib\tools.jar Unknown argument: --version ant [options] [target [target2 [target3] ...]] Options: -help, -h print this message -projecthelp, -p print project help information -version print the version information and exit ......
但是可以看到有tools.jar找不到的警告，不过根据该教程提示，可忽略之。
5.教程说是要下载Saxon 6.5.x，但是我此处下载和安装的是上面所说的9.4.0.4了，然后才注意到，原来是应该下载java版本的saxon的，
即SaxonHE9-4-0-4J.zip，解压后对应的是saxon9he.jar和saxon9-unpack.jar两个文件。
注：其他saxon版本，也可以去这里找到。
虽然教程说build.xml只对saxon 6.5测试过，但是此处暂时先试试saxon 9.4.0.4he的版本，如果最后不行，再去下载6.5版本的。
6.去安装教程，修改：
docbook-xsl-ns-1.77.0\webhelp\build.properties
结果将其和官网的比较，到配置xslt-processor-classpath时，本地的是：
xslt-processor-classpath=/usr/share/java/saxon-6.5.5.jar xercesImpl.jar=/usr/share/java/xercesImpl.jar xml-apis.jar=/usr/share/java/xml-apis.jar
官网的是：
xslt-processor-classpath=/usr/share/java/saxon-6.5.5.jar
所以是多了xercesImpl.jar和xml-apis.jar
7.关于这两个jar包，这里说是ant 1.8.0升至1.8.1时，就不再包含此俩jar包了。
而关于这两个包，和上述同样的教程但是更新的版本的：README: Web-based Help from DocBook XML – Chapter 2. Using the package也说了，ant 1.8.1后就没了。
看来是需要我们自己下载了。
8.然后分别下载了xml-apis.jar和xercesImpl.jar。然后后来看到docbook-xsl-ns-1.77.0\extensions中本来就有saxon65.jar，所以就把此俩jar都放到该文件夹中了。
然后对应的改为：
#xslt-processor-classpath=/usr/share/java/saxon-6.5.5.jar xslt-processor-classpath=/cygdrive/e/Dev_Tools/saxon/SaxonHE9-4-0-4J/saxon9he.jar #xercesImpl.jar=/usr/share/java/xercesImpl.jar xercesImpl.jar=/cygdrive/e/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.0/extensions/xercesImpl.jar #xml-apis.jar=/usr/share/java/xml-apis.jar xml-apis.jar=/cygdrive/e/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.0/extensions/xml-apis.jar
9.然后又把默认的
validate-against-dtd=false
改为
validate-against-dtd=true
然后其他的设置都保持默认。
10.然后打开Cygwin，进入到webhelp文件夹下，运行，结果出错：
Administrator@K470 /cygdrive/e/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.0/webhelp
$ ant webhelp -Doutput-dir=test-ouput
cygwin warning:
MS-DOS style path detected: E:\dev_install_root\apache_ant\apache-ant-1.8.4
Preferred POSIX equivalent is: /cygdrive/e/dev_install_root/apache_ant/apache-ant-1.8.4
CYGWIN environment variable option "nodosfilewarning" turns off this warning.
Consult the user's guide for more details about POSIX paths:
http://cygwin.com/cygwin-ug-net/using.html#using-pathnames
Unable to locate tools.jar. Expected to find it in D:\Program Files\Java\jre7\lib\tools.jar
Buildfile: E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.0\webhelp\build.xml
validate:
BUILD FAILED
E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.0\webhelp\build.xml:24: Could not start xml validation: org.apache.xerces.parsers.SAXParser
Total time: 0 seconds11.看起来像是验证的问题，所以去把validate关闭，即再将
validate-against-dtd=true
改回
validate-against-dtd=false
然再试试。
12。结果却又出现了"属性 ‘href’ 在元素外部",后得知对应英文为"Attribute ‘href’ outside of element"的错误，具体折腾和解决过程，可参见：
【已解决】用saxon编译docbook为webhelp过程中，使用ant出错：属性 ‘href’ 在元素外部 / Attribute ‘href’ outside of element
13.编译成功后，然后去docbook-xsl-ns-1.77.0\webhelp\test-ouput下面，用IE打开index.html，就可以看到webhelp的内容了：
14.然后又去折腾了尝试其他几个版本的saxon：
（1）试了试把
xslt-processor-classpath=E:/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.0/extensions/saxon-6.5.5.jar
换为
xslt-processor-classpath=E:/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.0/extensions/saxon65.jar
结果就会出现上面的的错误：
属性 ‘href’ 在元素外部
（2）而换为saxon9he.jar的话：
xslt-processor-classpath=E:/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.0/extensions/saxon9he.jar
就会出现如下错误：
Administrator@K470 /cygdrive/e/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.0/webhelp
$ ant webhelp -Doutput-dir=test-ouput
Unable to locate tools.jar. Expected to find it in D:\Program Files\Java\jre7\lib\tools.jar
Buildfile: E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.0\webhelp\build.xml
validate:
clean:
[delete] Deleting directory E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.0\webhelp\test-ouput
chunk:
[mkdir] Created dir: E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.0\webhelp\test-ouput
[xslt] Processing E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.0\webhelp\docsrc\readme.xml to E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.0\webhelp\test-ouput\null1978188777
[xslt] Loading stylesheet E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.0\profiling\profile.xsl
[xslt] Processing E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.0\webhelp\test-ouput\null1978188777 to E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.0\webhelp\test-ouput\null226003174
[xslt] Loading stylesheet E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.0\webhelp\xsl\webhelp.xsl
[xslt] : Warning! Stylesheet module file:/E:/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.0/common/utility.xsl is included or imported more than once. This is permitted, but may lead to errors or unexpected behavior
[xslt] E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.0\webhelp\xsl\webhelp-common.xsl:609:43: Warning! A variable with no following sibling instructions has no effect
[xslt] language: zh
[xslt] Don't know how to chunk with Saxonica
[xslt] Failed to process E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.0\webhelp\test-ouput\null1978188777
BUILD FAILED
E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.0\webhelp\build.xml:61: ; SystemID: file:/E:/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.0/xhtml/chunker.xsl; Line#: 55; Column#: -1
net.sf.saxon.expr.instruct.TerminationException: Processing terminated by xsl:message at line 55 in chunker.xsl
at net.sf.saxon.expr.instruct.Message.processLeavingTail(Message.java:223)
at net.sf.saxon.expr.instruct.Block.processLeavingTail(Block.java:615)
at net.sf.saxon.expr.instruct.Template.expand(Template.java:231)
at net.sf.saxon.expr.instruct.CallTemplate.process(CallTemplate.java:338)
at net.sf.saxon.expr.instruct.DocumentInstr.evaluateItem(DocumentInstr.java:334)
at net.sf.saxon.expr.parser.ExpressionTool.evaluate(ExpressionTool.java:320)
at net.sf.saxon.expr.instruct.GeneralVariable.getSelectValue(GeneralVariable.java:529)
at net.sf.saxon.expr.instruct.Instruction.assembleParams(Instruction.java:187)
at net.sf.saxon.expr.instruct.CallTemplate.processLeavingTail(CallTemplate.java:369)
at net.sf.saxon.expr.instruct.Block.processLeavingTail(Block.java:615)
at net.sf.saxon.expr.LetExpression.processLeavingTail(LetExpression.java:586)
at net.sf.saxon.expr.instruct.Block.processLeavingTail(Block.java:615)
at net.sf.saxon.expr.instruct.Template.expand(Template.java:231)
at net.sf.saxon.expr.instruct.CallTemplate$CallTemplatePackage.processLeavingTail(CallTemplate.java:526)
at net.sf.saxon.trans.Mode.applyTemplates(Mode.java:1007)
at net.sf.saxon.expr.instruct.ApplyTemplates.apply(ApplyTemplates.java:237)
at net.sf.saxon.expr.instruct.ApplyTemplates.processLeavingTail(ApplyTemplates.java:199)
at net.sf.saxon.expr.instruct.Block.processLeavingTail(Block.java:615)
at net.sf.saxon.expr.LetExpression.processLeavingTail(LetExpression.java:586)
at net.sf.saxon.expr.instruct.Block.processLeavingTail(Block.java:615)
at net.sf.saxon.expr.instruct.Instruction.process(Instruction.java:131)
at net.sf.saxon.expr.instruct.ElementCreator.processLeavingTail(ElementCreator.java:301)
at net.sf.saxon.expr.instruct.ElementCreator.processLeavingTail(ElementCreator.java:254)
at net.sf.saxon.expr.instruct.Block.processLeavingTail(Block.java:615)
at net.sf.saxon.expr.instruct.Template.applyLeavingTail(Template.java:212)
at net.sf.saxon.expr.instruct.Template.apply(Template.java:194)
at net.sf.saxon.expr.instruct.ApplyImports.processLeavingTail(ApplyImports.java:282)
at net.sf.saxon.expr.instruct.Instruction.process(Instruction.java:131)
at net.sf.saxon.expr.instruct.DocumentInstr.evaluateItem(DocumentInstr.java:334)
at net.sf.saxon.expr.parser.ExpressionTool.evaluate(ExpressionTool.java:320)
at net.sf.saxon.expr.instruct.GeneralVariable.getSelectValue(GeneralVariable.java:529)
at net.sf.saxon.expr.instruct.LocalParamSetter.processLeavingTail(LocalParamSetter.java:274)
at net.sf.saxon.expr.instruct.Block.processLeavingTail(Block.java:615)
at net.sf.saxon.expr.instruct.Template.expand(Template.java:231)
at net.sf.saxon.expr.instruct.CallTemplate$CallTemplatePackage.processLeavingTail(CallTemplate.java:526)
at net.sf.saxon.expr.instruct.ApplyTemplates.apply(ApplyTemplates.java:239)
at net.sf.saxon.expr.instruct.ApplyTemplates.processLeavingTail(ApplyTemplates.java:199)
at net.sf.saxon.expr.instruct.Block.processLeavingTail(Block.java:615)
at net.sf.saxon.expr.instruct.Template.applyLeavingTail(Template.java:212)
at net.sf.saxon.trans.Mode.applyTemplates(Mode.java:1034)
at net.sf.saxon.trans.TextOnlyCopyRuleSet.process(TextOnlyCopyRuleSet.java:58)
at net.sf.saxon.trans.Mode.applyTemplates(Mode.java:1022)
at net.sf.saxon.expr.instruct.ApplyTemplates.apply(ApplyTemplates.java:237)
at net.sf.saxon.expr.instruct.ApplyTemplates.processLeavingTail(ApplyTemplates.java:199)
at net.sf.saxon.expr.instruct.Block.processLeavingTail(Block.java:615)
at net.sf.saxon.expr.instruct.Choose.processLeavingTail(Choose.java:794)
at net.sf.saxon.expr.instruct.Block.processLeavingTail(Block.java:615)
at net.sf.saxon.expr.instruct.Choose.processLeavingTail(Choose.java:794)
at net.sf.saxon.expr.instruct.Block.processLeavingTail(Block.java:615)
at net.sf.saxon.expr.instruct.Template.applyLeavingTail(Template.java:212)
at net.sf.saxon.trans.Mode.applyTemplates(Mode.java:1034)
at net.sf.saxon.Controller.transformDocument(Controller.java:1957)
at net.sf.saxon.Controller.transform(Controller.java:1803)
at org.apache.tools.ant.taskdefs.optional.TraXLiaison.transform(TraXLiaison.java:195)
at org.apache.tools.ant.taskdefs.XSLTProcess.process(XSLTProcess.java:853)
at org.apache.tools.ant.taskdefs.XSLTProcess.execute(XSLTProcess.java:389)
at org.apache.tools.ant.UnknownElement.execute(UnknownElement.java:291)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
at java.lang.reflect.Method.invoke(Unknown Source)
at org.apache.tools.ant.dispatch.DispatchUtils.execute(DispatchUtils.java:106)
at org.apache.tools.ant.Task.perform(Task.java:348)
at org.apache.tools.ant.Target.execute(Target.java:392)
at org.apache.tools.ant.Target.performTasks(Target.java:413)
at org.apache.tools.ant.Project.executeSortedTargets(Project.java:1399)
at org.apache.tools.ant.Project.executeTarget(Project.java:1368)
at org.apache.tools.ant.helper.DefaultExecutor.executeTargets(DefaultExecutor.java:41)
at org.apache.tools.ant.Project.executeTargets(Project.java:1251)
at org.apache.tools.ant.Main.runBuild(Main.java:811)
at org.apache.tools.ant.Main.startAnt(Main.java:217)
at org.apache.tools.ant.launch.Launcher.run(Launcher.java:280)
at org.apache.tools.ant.launch.Launcher.main(Launcher.java:109)
Total time: 4 seconds所以，结论是，必须用saxon6-5-5版本的jar，即saxon6-5-5.zip解压后所得到的那个saxon.jar，才可以正常编译。
15.暂时对于把：
webhelp.indexer.language=en
换为：
webhelp.indexer.language=zh
好像没什么效果，估计是当内容为中文时，也许才有效果。待后续折腾才知道结果。
16.剩下的,就是有空把自己的各个book的docbook源码,都弄进来测试测试,看看效果如何了.
【总结：多个版本的Web-based Help from DocBook XML的教程】
至此，总结一下，关于用saxon编译docbook为webhelp的教程的地址：
（1）http://snapshots.docbook.org/xsl/webhelp/docs/content/ch02s01.html
始终保持最新的，docbook的snapshot的地址
（2）http://50.56.245.89/xsl-ns/webhelp/docs/content/ch04.html
某人的xsl-ns的地址，其中就是现在这里找到问题解答的，后来发现（1）中，早就有了。
（3）http://docbook.sourceforge.net/release/xsl/1.76.1/webhelp/docs/content/ch02s01.html
旧的1.76.1版本的
（4）http://vulture.gentoo.org/~kasun/docbook/docbook-webhelp-snapshot-current/content/ch01.html
某个叫kasun的，虽然不是最新的，但是也只有该教程提示了ant 1.8.1中没了那两个jar包的。
推荐使用（1）和（4）两个教程，都仔细看看，好好参考参考，你会发现很有用的，尤其是各种提示和FAQ。
转载请注明：在路上 » 【已成功】用Saxon将Docbook生成Webhelp