【问题】
已经实现了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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 | # 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
中的内容为:
1 2 3 4 | < 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 | < 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 < 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | <? 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 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 | <? xml version = "1.0" ?> <!DOCTYPE stylesheet [ <!ENTITY xsl_ns_path "E:/Dev_Root/docbook/tools/docbook-xsl-ns-1.77.1"> ]> 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:include href = "webhelp-common.xsl" /> < xsl:include href = "titlepage.templates.xsl" /> </ xsl:stylesheet > |
主要改动有:
A。虽然都是导入chunk.xsl,但由于此处挪了位置,所以此处也要改为对应的路径。
其中注意此处前缀必须是file:///,否则会出错,详情可参考:
(4)webhelp-common.xsl
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | < xsl:stylesheet 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。通过:
1 2 3 4 5 | < 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。通过:
1 | < 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内容贴出来,供需要的人参考:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | /* * about html color and corresponding name can refer: */ /* 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