【问题】
已经实现了ant webhelp,但是是基于修改了原先的docbook-xsl-ns-1.77.1来实现的。
现在目的是为了实现当前docbook环境中,只在config目录中,包含所有的自己的改动,而不去改动tools中的docbook-xsl-ns-1.77.1,的前提下,实现ant webhelp的功能。
【解决过程】
经过一番调试折腾,最后终于搞定了。
当前方案如下:
1. E:\Dev_Root\docbook\dev\ant\extensions下存放了所用到的几个jar包:
saxon-6.5.5.jar
xercesImpl.jar
xml-apis.jar
2.E:\Dev_Root\docbook\dev\ant\webhelp下存放了核心的ant相关配置文件:
(1)build.properties
# The path (relative to the build.xml file) to your input document. # To use your own input document, create a build.xml file of your own # and import this build.xml. # set this in specific docbook book xml file name #input-xml=docsrc/readme.xml # The directory in which to put the output files. # This directory is created if it does not exist. #output-dir=docs # current dir is docbook book src output-dir=../output/webhelp # If you are using a customization layer that imports webhelp.xsl, use # this property to point to it. #stylesheet-path=${ant.file.dir}/xsl/webhelp.xsl stylesheet-path=E:/Dev_Root/docbook/dev/ant/webhelp/xsl/webhelp_crl.xsl # If your document has image directories that need to be copied # to the output directory, you can list patterns here. # See the Ant documentation for fileset for documentation # on patterns. input-images-dirs=images/**,figures/**,graphics/** # By default, the ant script assumes your images are stored # in the same directory as the input-xml. If you store your # image directories in another directory, specify it here. # and uncomment this line. #input-images-basedir=/path/to/image/location # Modify the follosing so that they point to your local # copy of the jars indicated: # * Saxon 6.5 jar # * Xerces 2: xercesImpl.jar # * xml-commons: xml-apis.jar #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=E:/Dev_Root/docbook/dev/ant/extensions/saxon-6.5.5.jar xercesImpl.jar=E:/Dev_Root/docbook/dev/ant/extensions/xercesImpl.jar xml-apis.jar=E:/Dev_Root/docbook/dev/ant/extensions/xml-apis.jar # For non-ns version only, this validates the document # against a dtd. validate-against-dtd=false # The extension for files to be indexed (html/htm/xhtml etc.) html.extension=html # Set this to false if you don't need a search tab. webhelp.include.search.tab=true # indexer-language is used to tell the search indexer which language # the docbook is written. This will be used to identify the correct # stemmer, and punctuations that differs from language to language. # see the documentation for details. en=English, fr=French, de=German, # zh=Chinese, ja=Japanese etc. webhelp.indexer.language=en #webhelp.indexer.language=zh # Enables/Disables stemming # Stemming allows better querying for the search enable.stemming=true #Set the table of contents file. This file will not be indexed. #toc.file=dummy.html #Used for adding branding specific contents to the html files. #For example, the url docbook.org, Google Analytics id etc. branding=docbook brandname=DocBook # Set admon.graphics to 1 to user graphics for note, tip, etc. #admon.graphics=0 admon.graphics=1 suppress.footer.navigation=0 #xsl-ns base dir xsl-ns-path=E:/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.1
其中需要解释的是:
A。input-xml之所以被注释掉,是由于会被不同的docbook中的build.xml去设置,比如:
E:\Dev_Root\docbook\dev\books\docbook_dev_note\src\build.xml
中的内容为:
<project> <property name="input-xml" value="docbook_dev_note.xml"/> <import file="E:/Dev_Root/docbook/dev/ant/webhelp/build.xml"/> </project>
即每个book只需制定对应的入口的xml文件名和对应的,统一的webhelp的那个build.xml即可。
B。output-dir,每个都是对应的../output/webhelp,注意当前此时文件夹时所在dobcook中的某个book的src文件夹下。
C:stylesheet-path,是用到了我自己写的E:/Dev_Root/docbook/dev/ant/webhelp/xsl/webhelp_crl.xsl。
D:xslt-processor-classpath,xercesImpl.jar,xml-apis.jar,则是都引用到了extensions目录下的那几个jar包。
E:webhelp.indexer.language,注意,由于当前没有去实现对应的zh的支持,所以此处不能直接改为zh,否则会导致连基本的英文内容搜索都不支持了。
即,只有你自己真正实现了zh的支持,此处才能去改为对应的zh。具体如何实现中文搜索支持,官网有解释:
README: Web-based Help from DocBook XML – Search
F:xsl-ns-path,是新添加的变量,用于指定xsl-ns的位置,build.xml中会用到。
(2)build.xml
<project default="help" name="mainbuild"> <dirname property="ant.file.dir" file="${ant.file.mainbuild}"/> <loadproperties srcFile="${ant.file.dir}/build.properties"/> <property name="webhelp.include.search.tab" value="true"/> <!-- <property name="extensions.dir" value="${ant.file.dir}/../extensions"/> --> <property name="extensions.dir" value="${xsl-ns-path}/extensions"/> <path id="classpath"> <pathelement location="${extensions.dir}/webhelpindexer.jar"/> <pathelement location="${extensions.dir}/lucene-analyzers-3.0.0.jar"/> <pathelement location="${extensions.dir}/lucene-core-3.0.0.jar"/> <pathelement location="${extensions.dir}/tagsoup-1.2.1.jar"/> </path> <condition property="perform-validation-dtd"> <equals arg1="${validate-against-dtd}" arg2="true"/> </condition> <condition property="do-search-indexing"> <equals arg1="${webhelp.include.search.tab}" arg2="true"/> </condition> <target name="validate" if="perform-validation-dtd"> <xmlvalidate file="${input-xml}" classname="org.apache.xerces.parsers.SAXParser"/> </target> <target name="chunk" depends="clean"> <mkdir dir="${output-dir}"/> <tempfile destdir="${output-dir}" deleteonexit="true" property="xincluded-profiled.xml"/> <tempfile destdir="${output-dir}" deleteonexit="true" property="dummy.html"/> <xslt in="${input-xml}" out="${xincluded-profiled.xml}" style="${xsl-ns-path}/profiling/profile.xsl" classpath="${xercesImpl.jar}"> <sysproperty key="org.apache.xerces.xni.parser.XMLParserConfiguration" value="org.apache.xerces.parsers.XIncludeParserConfiguration"/> <param name="profile.arch" expression="${profile.arch}" if="profile.arch"/> <param name="profile.audience" expression="${profile.audience}" if="profile.audience"/> <param name="profile.condition" expression="${profile.condition}" if="profile.condition"/> <param name="profile.conformance" expression="${profile.conformance}" if="profile.conformance"/> <param name="profile.lang" expression="${profile.lang}" if="profile.lang"/> <param name="profile.os" expression="${profile.os}" if="profile.os"/> <param name="profile.revision" expression="${profile.revision}" if="profile.revision"/> <param name="profile.revisionflag" expression="${profile.revisionflag}" if="profile.revisionflag"/> <param name="profile.role" expression="${profile.role}" if="profile.role"/> <param name="profile.security" expression="${profile.security}" if="profile.security"/> <param name="profile.status" expression="${profile.status}" if="profile.status"/> <param name="profile.userlevel" expression="${profile.userlevel}" if="profile.userlevel"/> <param name="profile.vendor" expression="${profile.vendor}" if="profile.vendor"/> <param name="profile.wordsize" expression="${profile.wordsize}" if="profile.wordsize"/> <param name="profile.attribute" expression="${profile.attribute}" if="profile.attribute"/> <param name="profile.value" expression="${profile.value}" if="profile.value"/> </xslt> <xslt in="${xincluded-profiled.xml}" out="${dummy.html}" style="${stylesheet-path}" scanincludeddirectories="false" classpath="${xslt-processor-classpath}"> <param name="webhelp.include.search.tab" expression="${webhelp.include.search.tab}" if="webhelp.include.search.tab"/> <param name="output_file_name" expression="${output_file_name}"/> <param name="webhelp.base.dir" expression="${output-dir}" if="output-dir"/> <param name="webhelp.indexer.language" expression="${webhelp.indexer.language}" if="webhelp.indexer.language"/> <param name="branding" expression="${branding}" if="branding"/> <param name="brandname" expression="${brandname}" if="brandname"/> <param name="admon.graphics" expression="${admon.graphics}" if="admon.graphics"/> <param name="suppress.footer.navigation" expression="${suppress.footer.navigation}" if="suppress.footer.navigation"/> </xslt> <!-- Copy common content such as js files of tree, css etc. to template folder. They will be copied to doc folder. They are NOT page specific! --> <!-- <copy todir="${output-dir}"> <fileset dir="${xsl-ns-path}/webhelp/template"> <include name="**/*"/> <exclude name="**/content/search/**"/> </fileset> </copy> --> <!-- Very simple-minded copy to handle the source document's images --> <!-- TODO: Look at html help code that produces a manifest file...list of images --> <!-- Customize webhelp.xsl to produce ant file to copy images actually used? --> <dirname property="input-images-basedir" file="${input-xml}"/> <copy todir="${output-dir}/content" failonerror="false"> <fileset dir="${input-images-basedir}" includes="${input-images-dirs}" /> </copy> </target> <target name="index" if="do-search-indexing"> <!-- <copy todir="${output-dir}"> <fileset dir="${xsl-ns-path}/webhelp/template"> <include name="**/*"/> <exclude name="**/content/search/*.props"/> <exclude name="**/content/search/stemmers/*"/> </fileset> </copy> --> <copy todir="${output-dir}"> <fileset dir="${xsl-ns-path}/webhelp/template"> <include name="**/content/search/nwSearchFnt.js"/> </fileset> </copy> <!-- We separate this out so we only copy the stopwords list and stemmer for the indexer language --> <copy todir="${output-dir}"> <fileset dir="${xsl-ns-path}/webhelp/template"> <include name="**/content/search/default.props"/> <include name="**/content/search/punctuation.props"/> <include name="**/content/search/${webhelp.indexer.language}*.props"/> <include name="**/content/search/stemmers/${webhelp.indexer.language}_stemmer.js"/> </fileset> </copy> <!--taskdef name="indexertask" classname="com.nexwave.nquindexer.IndexerMain"> <classpath refid="classpath"/> </taskdef--> <echo>Indexing html files in ${output-dir}/content</echo> <java classname="com.nexwave.nquindexer.IndexerMain" fork="true"> <sysproperty key="htmlDir" value="${output-dir}/content"/> <sysproperty key="indexerLanguage" value="${webhelp.indexer.language}"/> <sysproperty key="htmlExtension" value="${html.extension}"/> <sysproperty key="doStem" value="${enable.stemming}"/> <sysproperty key="tocFile" value="${toc.file}"/> <!--TagSoup SAX Parser for parsing even the bad html contents. see http://sourceforge.net/tracker/?func=detail&aid=3401185&group_id=21935&atid=373750--> <sysproperty key="org.xml.sax.driver" value="org.ccil.cowan.tagsoup.Parser"/> <sysproperty key="javax.xml.parsers.SAXParserFactory" value="org.ccil.cowan.tagsoup.jaxp.SAXFactoryImpl"/> <!-- Uncomment the following if Xerces is your preference as the SAX XML Parser. Note that the indexing will fail with Xerces if the html files are not XML-conformance --> <!--sysproperty key="org.xml.sax.driver" value="org.apache.xerces.parsers.SAXParser"/> <sysproperty key="javax.xml.parsers.SAXParserFactory" value="org.apache.xerces.jaxp.SAXParserFactoryImpl"/--> <!-- Debug the indexer on port 5005 via remote-debug --> <!--jvmarg line="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005"/--> <classpath> <path refid="classpath"/> <pathelement location="${xercesImpl.jar}"/> <pathelement location="${xml-apis.jar}"/> <!-- <pathelement location="/usr/share/java/xercesImpl.jar"/> --> <!-- <pathelement location="/usr/share/java/xml-apis.jar"/> --> <!-- Gentoo Linux friendly default classpath--> <pathelement location="/usr/share/xerces-2/lib/xercesImpl.jar"/> <pathelement location="/usr/share/xml-commons/lib/xml-apis.jar"/> </classpath> </java> <delete> <fileset dir="${output-dir}/content/search" includes="*.props"/> </delete> </target> <target name="webhelp" depends="validate,chunk,index"/> <target name="clean"> <delete dir="${output-dir}"/> </target> <target name="help"> <echo> Usage: webhelp: Generates the document in webhelp format and indexes the content. clean: Deletes webhelp output directory. index: Indexes the content. </echo> </target> </project>
可以看出看,主要改动在于:
A。把extensions.dir改为对应的xsl-ns-path下面的extensions了。
B。把那几个copy todir="${output-dir}基本都去掉了。这样,是为了对于每个docbook编译出来后,目前下都没有这些基本的css,html等框架文件了,而使其去到一个公共的位置去加载。
此公共位置,支持两种,一种是本地的某个文件夹,一个是在线的某个路径下的相关文件。
3. E:\Dev_Root\docbook\dev\ant\webhelp\xsl下有对应的各个xsl配置文件:
(1)titlepage.templates.xml和titlepage.templates.xsl,没有变,只是从E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.1\webhelp\xsl拷贝过来的而已。
(2)webhelp_crl.xsl
<?xml version="1.0"?> <!DOCTYPE stylesheet [ <!ENTITY xsl_ns_path "E:/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.1"> <!ENTITY config_path "E:/Dev_Root/docbook/dev/config/docbook-xsl-ns-1.77.1"> ]> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:d="http://docbook.org/ns/docbook" xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" xmlns:exsl="http://exslt.org/common" xmlns:set="http://exslt.org/sets" version="1.0" exclude-result-prefixes="doc exsl set d"> <!-- <xsl:import href="file:///E:/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.1/webhelp/xsl/webhelp.xsl"/> --> <xsl:import href="webhelp.xsl"/> <!-- desitinate the dir of webhelp common resource currently those resources include common/ and favicon.ico --> <!--<xsl:param name="webhelp.common.dir">E:/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.1/webhelp/docs/common/</xsl:param>--> <!--<xsl:param name="webhelp.common.dir">&xsl_ns_path;/webhelp/docs/common/</xsl:param>--> <xsl:param name="webhelp.common.dir">&xsl_ns_path;/webhelp/template/common/</xsl:param> <!-- custom css file path --> <xsl:param name="custom.css.path">&config_path;/html/css/common_html.css</xsl:param> <!--<xsl:param name="custom.css.path">https://www.crifan.com/files/res/docbook/css/common_html.css</xsl:param>--> </xsl:stylesheet>
作用主要有:
A。先导入webhelp.xsl
B。再添加一个变量webhelp.common.dir,用于指定此处我的xsl-ns下的webhelp/template/common中的路径。
C。添加一个自定义css文件:custom.css.path,用于后面要介绍到的webhelp-common.xsl,插入对应的生成页面中,实现自己所要的html的效果。
(3)webhelp.xsl
<?xml version="1.0"?> <!DOCTYPE stylesheet [ <!ENTITY xsl_ns_path "E:/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.1"> ]> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:d="http://docbook.org/ns/docbook" xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" xmlns:exsl="http://exslt.org/common" xmlns:set="http://exslt.org/sets" version="1.0" exclude-result-prefixes="doc exsl set d"> <!-- ******************************************************************** $Id$ ******************************************************************** This file is part customization layer on top of the XSL DocBook Stylesheet distribution that generates webhelp output. ******************************************************************** --> <!-- <xsl:import href="../../xhtml/chunk.xsl"/> <xsl:include href="webhelp-common.xsl"/> <xsl:include href="titlepage.templates.xsl"/> --> <!--<xsl:import href="file:///E:/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.1/xhtml/chunk.xsl"/>--> <xsl:import href="file:///&xsl_ns_path;/xhtml/chunk.xsl"/> <xsl:include href="webhelp-common.xsl"/> <xsl:include href="titlepage.templates.xsl"/> </xsl:stylesheet>
主要改动有:
A。虽然都是导入chunk.xsl,但由于此处挪了位置,所以此处也要改为对应的路径。
其中注意此处前缀必须是file:///,否则会出错,详情可参考:
(4)webhelp-common.xsl
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:d="http://docbook.org/ns/docbook" xmlns:exsl="http://exslt.org/common" xmlns:ng="http://docbook.org/docbook-ng" xmlns:db="http://docbook.org/ns/docbook" version="1.0" xmlns="http://www.w3.org/1999/xhtml" exclude-result-prefixes="exsl ng db d"> .... ... ... .ui-tabs { padding: .2em;} .ui-tabs .ui-tabs-nav li { top: 0px; margin: -2px 0 1px; text-transform: uppercase; font-size: 10.5px;} .ui-tabs .ui-tabs-nav li a { padding: .25em 2em .25em 1em; margin: .5em; text-shadow: 0 1px 0 rgba(255,255,255,.5); } </style> <xsl:comment> <xsl:text>[if IE]><link rel="stylesheet" type="text/css" href="</xsl:text> <xsl:value-of select="$webhelp.common.dir"/> <xsl:text>/css/ie.css"/><![endif]</xsl:text> </xsl:comment> <link rel="stylesheet" type="text/css" href="{$custom.css.path}" /> <!-- browserDetect is an Oxygen addition to warn the user if they're using chrome from the file system. This breaks the Oxygen search highlighting. --> <script type="text/javascript" src="{$webhelp.common.dir}browserDetect.js"> <xsl:comment> </xsl:comment> </script> ... ... ... </xsl:stylesheet>
其中,主要改动为:
A。通过:
<xsl:comment> <xsl:text>[if IE]><link rel="stylesheet" type="text/css" href="</xsl:text> <xsl:value-of select="$webhelp.common.dir"/> <xsl:text>/css/ie.css"/><![endif]</xsl:text> </xsl:comment>
就实现了,所有的template/common下面的所有css,html页面,js脚本等所有统一的资源内容,都使用之前webhelp.common.dir所指定的位置的。
这样,多个docbook所生成的webhelp,就都不用再自己拥有一份拷贝,而使用此统一的模板配置了。
一是实现了省略资源拷贝,二是实现了统一管理模板配置。
B。通过:
<link rel="stylesheet" type="text/css" href="{$custom.css.path}" />
实现了,添加自己的css配置,实现自定义html显示效果。
其中,我的E:\Dev_Root\docbook\dev\config\docbook-xsl-ns-1.77.1\html\css\common_html.css内容贴出来,供需要的人参考:
/* * about html color and corresponding name can refer: * http://www.w3schools.com/html/html_colornames.asp */ /* programlisting */ pre.programlisting { /* background-color: #F4F4F4 ; */ background-color: Lavender ; border: 1px solid #006600 ; } /* screen */ pre.screen { /* background-color: #F4F4F4 ; */ background-color: Lavender ; border: 1px solid #006600 ; } /* equation */ div.equation { /* background-color: #F4F4F4 ; */ background-color: Lavender ; border: 1px solid #006600 ; } /* table */ /* thead=table header */ thead { background-color: antiquewhite ; } /* QandA: Question and Answer */ tr.question { background-color: antiquewhite ; }
4.最后,当前还需要对应的完整的docbook-xsl-ns-1.77.1的内容,是放在:
E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.1
下面了。
5.最后总体的文件夹架构是:
至此,就实现了,在不改动原有的docbook-xsl-ns-1.77.1,而实现了将ant webhelp整合到当前docbook开发环境中去了。
转载请注明:在路上 » 【已解决】把ant webhelp合并到当前Docbook环境中,且保持不修改原先的docbook-xsl-ns-1.77.1