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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head>
<meta http-equiv="X-UA-Compatible" content="IE=edge"></meta>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"></meta>
<title>Generating webhelp output using the Ant build.xml file - - README: Web-based Help from DocBook XML</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></meta><meta name="description" content="Installation instructions"></meta><link rel="home" href="index.html" title="README: Web-based Help from DocBook XML"></link><link rel="up" href="ch02.html" title="Using the package"></link><link rel="prev" href="ch02.html" title="Using the package"></link><link rel="next" href="ch02s02.html" title="Using and customizing the output"></link><meta name="Section-title" content="Generating webhelp output using the Ant build.xml file"></meta><script type="text/javascript">
//The id for tree cookie
var treeCookieId = "treeview-1102";
var language = "en";
var w = new Object();
//Localization
txt_filesfound = 'Results';
txt_enter_at_least_1_char = "You must enter at least one character.";
txt_browser_not_supported = "JavaScript is disabled on your browser. Please enable JavaScript to enjoy all the features of this site.";
txt_please_wait = "Please wait. Search in progress...";
txt_results_for = "Results for: ";
</script><link rel="shortcut icon" href="favicon.ico" type="image/x-icon"></link><link rel="stylesheet" type="text/css" href="common/css/positioning.css"></link><link rel="stylesheet" type="text/css" href="common/jquery/theme-redmond/jquery-ui-1.8.2.custom.css"></link><link rel="stylesheet" type="text/css" href="common/jquery/treeview/jquery.treeview.css"></link><style type="text/css">
#noscript{
font-weight:bold;
background-color: #55AA55;
font-weight: bold;
height: 25spx;
z-index: 3000;
top:0px;
width:100%;
position: relative;
border-bottom: solid 5px black;
text-align:center;
color: white;
}
input {
margin-bottom: 5px;
margin-top: 2px;
}
.folder {
display: block;
height: 22px;
padding-left: 20px;
background: transparent url(common/jquery/treeview/images/folder.gif) 0 0px no-repeat;
}
span.contentsTab {
padding-left: 20px;
background: url(common/images/toc-icon.png) no-repeat 0 center;
}
span.searchTab {
padding-left: 20px;
background: url(common/images/search-icon.png) no-repeat 0 center;
}
/* Overide jquery treeview's defaults for ul. */
.treeview ul {
background-color: transparent;
margin-top: 4px;
}
#webhelp-currentid {
background-color: #D8D8D8 !important;
}
.treeview .hover { color: black; }
.filetree li span a { text-decoration: none; font-size: 12px; color: #517291; }
/* Override jquery-ui's default css customizations. These are supposed to take precedence over those.*/
.ui-widget-content {
border: 0px;
background: none;
color: none;
}
.ui-widget-header {
color: #e9e8e9;
border-left: 1px solid #e5e5e5;
border-right: 1px solid #e5e5e5;
border-bottom: 1px solid #bbc4c5;
border-top: 4px solid #e5e5e5;
border: medium none;
background: #F4F4F4; /* old browsers */
background: -moz-linear-gradient(top, #F4F4F4 0%, #E6E4E5 100%); /* firefox */
background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#F4F4F4), color-stop(100%,#E6E4E5)); /* webkit */
font-weight: none;
}
.ui-widget-header a { color: none; }
.ui-state-default, .ui-widget-content .ui-state-default, .ui-widget-header .ui-state-default {
border: none; background: none; font-weight: none; color: none; }
.ui-state-default a, .ui-state-default a:link, .ui-state-default a:visited { color: black; text-decoration: none; }
.ui-state-hover, .ui-widget-content .ui-state-hover, .ui-widget-header .ui-state-hover, .ui-state-focus, .ui-widget-content .ui-state-focus, .ui-widget-header .ui-state-focus { border: none; background: none; font-weight: none; color: none; }
.ui-state-active, .ui-widget-content .ui-state-active, .ui-widget-header .ui-state-active { border: none; background: none; font-weight: none; color: none; }
.ui-state-active a, .ui-state-active a:link, .ui-state-active a:visited {
color: black; text-decoration: none;
background: #C6C6C6; /* old browsers */
background: -moz-linear-gradient(top, #C6C6C6 0%, #D8D8D8 100%); /* firefox */
background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#C6C6C6), color-stop(100%,#D8D8D8)); /* webkit */
-webkit-border-radius:15px; -moz-border-radius:10px;
border: 1px solid #f1f1f1;
}
.ui-corner-all { border-radius: 0 0 0 0; }
.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); }
/**
* Basic Layout Theme
*
* This theme uses the default layout class-names for all classes
* Add any 'custom class-names', from options: paneClass, resizerClass, togglerClass
*/
.ui-layout-pane { /* all 'panes' */
background: #FFF;
border: 1px solid #BBB;
padding: 05x;
overflow: auto;
}
.ui-layout-resizer { /* all 'resizer-bars' */
background: #DDD;
top:100px
}
.ui-layout-toggler { /* all 'toggler-buttons' */
background: #AAA;
}
</style><!--[if IE]>
<link rel="stylesheet" type="text/css" href="../common/css/ie.css"/>
<![endif]--><script type="text/javascript" src="common/browserDetect.js"></script><script type="text/javascript" src="common/jquery/jquery-1.7.2.min.js"></script><script type="text/javascript" src="common/jquery/jquery.ui.all.js"></script><script type="text/javascript" src="common/jquery/jquery.cookie.js"></script><script type="text/javascript" src="common/jquery/treeview/jquery.treeview.min.js"></script><script type="text/javascript" src="common/jquery/layout/jquery.layout.js"></script><script type="text/javascript" src="search/l10n.js"></script><script type="text/javascript" src="search/htmlFileInfoList.js"></script><script type="text/javascript" src="search/nwSearchFnt.js"></script><script type="text/javascript" src="search/stemmers/en_stemmer.js"><!--//make this scalable to other languages as well.--></script><script type="text/javascript" src="search/index-1.js"></script><script type="text/javascript" src="search/index-2.js"></script><script type="text/javascript" src="search/index-3.js"></script></head><body><noscript><div id="noscript">JavaScript is disabled on your browser. Please enable JavaScript to enjoy all the features of this site.</div></noscript><div id="header"><a href="index.html"><img style="margin-right: 2px; height: 59px; padding-right: 25px; padding-top: 8px" align="right" src="common/images/logo.png" alt=" Documentation"></img></a><h1>README: Web-based Help from DocBook XML<br></br>Using the package</h1><div id="navheader"><table class="navLinks"><tr><td><a id="showHideButton" href="#" onclick="myLayout.toggle('west')" class="pointLeft" tabindex="5" title="Hide TOC tree">Sidebar
</a></td><td><a accesskey="p" class="navLinkPrevious" tabindex="5" href="ch02.html">Prev</a>
|
<a accesskey="u" class="navLinkUp" tabindex="5" href="ch02.html">Up</a>
|
<a accesskey="n" class="navLinkNext" tabindex="5" href="ch02s02.html">Next</a></td></tr></table></div></div><div id="content"><div class="section"><div xmlns="" class="titlepage"><div><div><h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a id="idp125040"></a>Generating webhelp output using the Ant build.xml
file</h2></div></div></div>
<div class="procedure"><a id="idp126912"></a><p class="title"><strong>Procedure 1. To install the package</strong></p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The examples in this procedure assume a Windows
installation, but the process is the same in other
environments, <span class="foreignphrase"><em class="foreignphrase">mutatis
mutandis</em></span>. In an environment where unix
shell command are available, you can also use the
<code class="filename">Makefile.sample</code> as a starting point
for creating your build script. To use
<code class="filename">Makefile.sample</code> you must have
<span class="command"><strong>xsltproc</strong></span> and <span class="command"><strong>java</strong></span>
available in your <code class="envar">PATH</code>. You can also use
the <a class="ulink" href="http://docbkx-tools.sourceforge.net/docbkx-samples/manual.html" target="_top">Docbkx Maven plugin</a> to generate webhelp.</p></div><ol class="procedure" type="1"><li class="step"><p>If necessary, install <a class="ulink" href="http://www.java.com/en/download/manual.jsp" target="_top">Java
1.6</a> or higher.</p><ol type="a" class="substeps"><li class="step"><p>Confirm that Java is installed and in your <code class="envar">PATH</code> by typing the
following at a command prompt: </p><pre class="programlisting">java -version</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>To build the indexer, you must have the JDK.</p></div></li></ol></li><li class="step"><p>If necessary, install <a class="ulink" href="http://ant.apache.org/bindownload.cgi" target="_top">Apache
Ant</a> 1.8.0 or higher. See <a class="ulink" href="http://ant.apache.org/manual/install.html" target="_top">Ant installation instructions</a>.</p><ol type="a" class="substeps"><li class="step"><p>Unzip the Ant binary distribution to a convenient location on your system. For
example: <code class="filename">c:\Program Files</code>.</p></li><li class="step"><p>Set the environment variable <code class="envar">ANT_HOME</code> to the top-level Ant
directory. For example: <code class="filename">c:\Program Files\apache-ant-1.8.0</code>. </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>See <a class="ulink" href="http://support.microsoft.com/kb/310519" target="_top">How To Manage
Environment Variables in Windows XP</a> for information on setting
environment variables.</p></div></li><li class="step"><p>Add the Ant <code class="filename">bin</code> directory to your <code class="envar">PATH</code>. For
example: <code class="filename">c:\Program Files\apache-ant-1.8.0\bin</code></p></li><li class="step"><p>Confirm that Ant is installed by typing the following at a command prompt:
</p><pre class="programlisting">ant -version</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If you see a message about the file <code class="filename">tools.jar</code> being
missing, you can safely ignore it.</p></div></li></ol></li><li class="step"><p>Download <a class="ulink" href="http://prdownloads.sourceforge.net/saxon/saxon6-5-5.zip" target="_top">Saxon
6.5.x</a> and unzip the distribution to a convenient location on your file system.
You will use the path to <code class="filename">saxon.jar</code> in <a class="xref" href="ch02s01.html#edit-build-properties" title="Step 5">Step 5</a> below.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The <code class="filename">build.xml</code> has only been tested with Saxon 6.5, though
it could be adapted to work with other XSLT processors. However, when you generate
output, the Saxon jar must <span class="bold"><strong>not</strong></span> be in your
<code class="envar">CLASSPATH</code>.</p></div></li><li class="step"><p>Download <a class="ulink" href="https://xerces.apache.org/xerces2-j/" target="_top">Xerces2
Java</a> and extract it to a convenient location on
your file system. You will need the
<code class="filename">xercesImpl.jar</code> and
<code class="filename">xml-apis.jar</code> from this distribution
in in <a class="xref" href="ch02s01.html#edit-build-properties" title="Step 5">Step 5</a>. </p></li><li class="step"><a id="edit-build-properties"></a><p>In a text editor, edit the
<code class="filename">build.properties</code> file in the
webhelp directory and make the changes indicated by the comments.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>You must set appropriate values for
<code class="code">xslt-processor-classpath</code>,
<code class="code">xercesImpl.jar</code>, and
<code class="code">xml-apis.jar</code>.</p></div><p>See the DocBook <a class="ulink" href="../../../doc/html/webhelp.html" target="_top">reference
documentation</a> for detailed information about the
available webhelp and other parameters. Note that not all
DocBook parameters are passed in to the xsls by the
<code class="filename">build.xml</code> by default. You may need
to modify the <code class="filename">build.xml</code> to pass in
some DocBook
parameters.</p><pre class="programlisting">
# 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.
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
# 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
# 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
<span class="emphasis"><em># 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
</em></span>
# For non-ns version only, this validates the document
# against a dtd.
validate-against-dtd=true
# 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
# Enables/Disables stemming
# Stemming allows better querying for the search
enable.stemming=true
# Set admon.graphics to 1 to user graphics for note, tip, etc.
admon.graphics=0
suppress.footer.navigation=0</pre></li><li class="step"><p>Test the package by running the command <code class="code">ant
webhelp -Doutput-dir=test-ouput</code> at the command
line in the webhelp directory. It should generate a copy
of this documentation in the <code class="filename">doc</code> directory. Type <code class="code">start
test-output\index.html</code> to open the output in a
browser. Once you have confirmed that the process worked,
you can delete the <code class="filename">test-output</code> directory. </p></li><li class="step"><p>To process your own document, simply refer to this package from another
<code class="filename">build.xml</code> in arbitrary location on your system:</p><ol type="a" class="substeps"><li class="step"><p>Create a new <code class="filename">build.xml</code> file that defines the name of your
source file, the desired output directory, and imports the
<code class="filename">build.xml</code> from this package. For example:
</p><pre class="programlisting"><project>
<property name="input-xml" value="<em class="replaceable"><code>path-to/yourfile.xml</code></em>"/>
<property name="input-images-dirs" value="<em class="replaceable"><code>images/** figures/** graphics/**</code></em>"/>
<property name="output-dir" value="<em class="replaceable"><code>path-to/desired-output-dir</code></em>"/>
<import file="<em class="replaceable"><code>path-to/docbook-webhelp/</code></em>build.xml"/>
</project></pre></li><li class="step"><p>From the directory containing your newly created <code class="filename">build.xml</code>
file, type <code class="code">ant webhelp</code> to build your document.</p></li></ol></li></ol></div></div><script type="text/javascript" src="common/main.js"></script><script type="text/javascript" src="common/splitterInit.js"></script><div class="navfooter"><hr></hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch02s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></div><div id="sidebar"><div id="leftnavigation" style="padding-top:3px;"><div id="tabs"><ul><li><a href="#treeDiv" style="outline:0;" tabindex="1"><span class="contentsTab">Contents</span></a></li><li><a href="#searchDiv" style="outline:0;" tabindex="1" onclick="doSearch()"><span class="searchTab">Search</span></a></li></ul><div id="treeDiv"><img src="common/images/loading.gif" alt="loading table of contents..." id="tocLoading" style="display:block;"></img><div id="ulTreeDiv" style="display:none"><ul id="tree" class="filetree"><li><span class="file"><a href="ch01.html" tabindex="1">Introduction</a></span></li><li><span class="file"><a href="ch02.html" tabindex="1">Using the package</a></span><ul><li id="webhelp-currentid"><span class="file"><a href="ch02s01.html" tabindex="1">Generating webhelp output using the Ant build.xml
file</a></span></li><li><span class="file"><a href="ch02s02.html" tabindex="1">Using and customizing the output</a></span><ul><li><span class="file"><a href="ch02s02s01.html" tabindex="1">Recommended Apache configurations</a></span></li></ul></li><li><span class="file"><a href="ch02s03.html" tabindex="1">Search indexing</a></span></li><li><span class="file"><a href="ch02s04.html" tabindex="1">Adding support for other (non-CJKV) languages</a></span></li><li><span class="file"><a href="ch02s05.html" tabindex="1">Adding images</a></span></li></ul></li><li><span class="file"><a href="ch03.html" tabindex="1">Developer Docs</a></span><ul><li><span class="file"><a href="ch03s01.html" tabindex="1">Design</a></span></li><li><span class="file"><a href="ch03s02.html" tabindex="1">Search</a></span><ul><li><span class="file"><a href="ch03s02s01.html" tabindex="1">New Stemmers</a></span></li></ul></li></ul></li><li><span class="file"><a href="ch04.html" tabindex="1">FAQ</a></span></li><li><span class="file"><a href="ch05.html" tabindex="1">Test section</a></span><ul><li><span class="file"><a href="ch05s01.html" tabindex="1">Some search words for testing</a></span></li><li><span class="file"><a href="ch05s02.html" tabindex="1">Some search words for testing (inflected)</a></span></li></ul></li><li><span class="file"><a href="ix01.html" tabindex="1">Index</a></span></li></ul></div></div><div id="searchDiv"><div id="search"><form onsubmit="Verifie(searchForm);return false" name="searchForm" class="searchForm"><div><input id="textToSearch" name="textToSearch" type="search" placeholder="Search" class="searchText" tabindex="1"></input> <input onclick="Verifie(searchForm)" type="button" class="searchButton" value="Go" id="doSearch" tabindex="1"></input></div></form></div><div id="searchResults"><center></center></div><p class="searchHighlight"><a href="#" onclick="toggleHighlight()">Search Highlighter (On/Off)</a></p></div></div></div></div></body></html>
|
