最新消息:20210816 当前crifan.com域名已被污染,为防止失联,请关注(页面右下角的)公众号

【已解决】把ant webhelp合并到当前Docbook环境中,且保持不修改原先的docbook-xsl-ns-1.77.1

Docbook crifan 1930浏览 0评论

【问题】

已经实现了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
    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="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: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">
]>
 
<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: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:include href="webhelp-common.xsl"/>
<xsl:include href="titlepage.templates.xsl"/>
 
</xsl:stylesheet>

主要改动有:

A。虽然都是导入chunk.xsl,但由于此处挪了位置,所以此处也要改为对应的路径。

其中注意此处前缀必须是file:///,否则会出错,详情可参考:

【已解决】docbook中,用ant使用saxon编译webhelp出错:Cause: java.io.EOFException: no more input … javax.xml.transform.TransformerConfigurationException: Failed to compile stylesheet. 1 error detected

(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
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        xmlns:d="http://docbook.org/ns/docbook"
        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]>&lt;link rel="stylesheet" type="text/css" href="</xsl:text>
        <xsl:value-of select="$webhelp.common.dir"/>
        <xsl:text>/css/ie.css"/>&lt;![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]>&lt;link rel="stylesheet" type="text/css" href="</xsl:text>
    <xsl:value-of select="$webhelp.common.dir"/>
    <xsl:text>/css/ie.css"/>&lt;![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 ant dir struct

 

至此,就实现了,在不改动原有的docbook-xsl-ns-1.77.1,而实现了将ant webhelp整合到当前docbook开发环境中去了。

转载请注明:在路上 » 【已解决】把ant webhelp合并到当前Docbook环境中,且保持不修改原先的docbook-xsl-ns-1.77.1

发表我的评论
取消评论

表情

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

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址
83 queries in 0.664 seconds, using 22.45MB memory