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

【问题】

已经实现了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.org/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:///，否则会出错，详情可参考：

【已解决】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

<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]>&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。通过：

    <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。通过：

<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