最新消息:20210917 已从crifan.com换到crifan.org

【已成功】用Saxon将Docbook生成Webhelp

Docbook crifan 2450浏览 0评论

【背景】

想要用Docbook输出尽可能多的格式。

目前已经可以输出HTML,HTMLs,PDF,Plain Text,CHM,RTF等格式了。

现在发现docbook-xsl-ns-1.76.1有个webhelp,所以想要看看是个啥东东,可以的话,也生成一个试试。

【折腾过程】

1.找到了:Using DocBook to Generate WebHelp,通过其截图:

webhelp example

然后又参考 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.jarxercesImpl.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 seconds

11.看起来像是验证的问题,所以去把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的内容了:

build webhelp ok using saxon

 

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

发表我的评论
取消评论

表情

Hi,您需要填写昵称和邮箱!

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址
89 queries in 0.235 seconds, using 20.41MB memory