[15c7d39] | 1 | <?xml version="1.0" encoding="UTF-8"?>
|
---|
| 2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
---|
| 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
|
---|
| 4 | <!ELEMENT xi:include (xi:fallback?) >
|
---|
| 5 | <!ATTLIST xi:include
|
---|
| 6 | xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude"
|
---|
| 7 | href CDATA #IMPLIED
|
---|
| 8 | parse (xml|text) "xml"
|
---|
| 9 | xpointer CDATA #IMPLIED
|
---|
| 10 | encoding CDATA #IMPLIED
|
---|
| 11 | accept CDATA #IMPLIED
|
---|
| 12 | accept-language CDATA #IMPLIED >
|
---|
| 13 |
|
---|
| 14 | <!ELEMENT xi:fallback ANY>
|
---|
| 15 | <!ATTLIST xi:fallback
|
---|
| 16 | xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude" >
|
---|
| 17 |
|
---|
| 18 | <!ENTITY % local.chapter.class "| xi:include">
|
---|
| 19 | ]>
|
---|
| 20 | <book>
|
---|
| 21 | <title>README: Web-based Help from DocBook XML</title>
|
---|
| 22 | <bookinfo>
|
---|
| 23 | <legalnotice>
|
---|
| 24 | <para>Permission is hereby granted, free of charge, to any person obtaining a copy of this
|
---|
| 25 | software and associated documentation files (the <quote>Software</quote>), to deal in the
|
---|
| 26 | Software without restriction, including without limitation the rights to use, copy, modify,
|
---|
| 27 | merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
|
---|
| 28 | persons to whom the Software is furnished to do so, subject to the following conditions: <itemizedlist>
|
---|
| 29 | <listitem>
|
---|
| 30 | <para>The above copyright notice and this permission notice shall be included in all
|
---|
| 31 | copies or substantial portions of the Software.</para>
|
---|
| 32 | </listitem>
|
---|
| 33 | <listitem>
|
---|
| 34 | <para>Except as contained in this notice, the names of individuals credited with
|
---|
| 35 | contribution to this software shall not be used in advertising or otherwise to promote
|
---|
| 36 | the sale, use or other dealings in this Software without prior written authorization
|
---|
| 37 | from the individuals in question.</para>
|
---|
| 38 | </listitem>
|
---|
| 39 | <listitem>
|
---|
| 40 | <para>Any stylesheet derived from this Software that is publicly distributed will be
|
---|
| 41 | identified with a different name and the version strings in any derived Software will
|
---|
| 42 | be changed so that no possibility of confusion between the derived package and this
|
---|
| 43 | Software will exist.</para>
|
---|
| 44 | </listitem>
|
---|
| 45 | </itemizedlist></para>
|
---|
| 46 | <formalpara>
|
---|
| 47 | <title>Warranty:</title>
|
---|
| 48 | <para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
|
---|
| 49 | INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
|
---|
| 50 | PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL DAVID CRAMER, KASUN GAJASINGHE, OR ANY
|
---|
| 51 | OTHER CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
|
---|
| 52 | ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
---|
| 53 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</para>
|
---|
| 54 | </formalpara>
|
---|
| 55 | <para>This package is maintained by Kasun Gajasinghe,
|
---|
| 56 | <email>kasunbg AT gmail DOT com</email> and David Cramer,
|
---|
| 57 | <email>david AT thingbag DOT net</email> and with
|
---|
| 58 | contributions by Arun Bharadwaj and Visitha Baddegama. Please
|
---|
| 59 | direct support questions to the <ulink
|
---|
| 60 | url="http://wiki.docbook.org/DocBookDiscussion">DocBook-apps
|
---|
| 61 | mailing list</ulink>. </para>
|
---|
| 62 | <para>This package also includes the following software written and copyrighted by others:<itemizedlist>
|
---|
| 63 | <listitem>
|
---|
| 64 | <para>Files in <filename class="directory">template/common/jquery</filename> are
|
---|
| 65 | copyrighted by <ulink url="http://jquery.com/">JQuery</ulink> under the MIT License.
|
---|
| 66 | The file <filename>jquery.cookie.js</filename> Copyright (c) 2006 Klaus Hartl under
|
---|
| 67 | the MIT license.</para>
|
---|
| 68 | <indexterm>
|
---|
| 69 | <primary>jquery</primary>
|
---|
| 70 | </indexterm>
|
---|
| 71 | </listitem>
|
---|
| 72 | <listitem>
|
---|
| 73 | <para>Some files in the <filename class="directory"
|
---|
| 74 | >template/search</filename> and <filename
|
---|
| 75 | class="directory">indexer</filename> directories were
|
---|
| 76 | originally part of N. Quaine's htmlsearch DITA plugin.
|
---|
| 77 | The htmlsearch DITA plugin is available from the <ulink
|
---|
| 78 | url="http://tech.groups.yahoo.com/group/dita-users/files/Demos/"
|
---|
| 79 | >files page</ulink> of the DITA-users yahoogroup. The
|
---|
| 80 | htmlsearch plugin was released under a BSD-style
|
---|
| 81 | license. See <filename>indexer/license.txt</filename>
|
---|
| 82 | for details. <indexterm>
|
---|
| 83 | <primary>htmlsearch</primary>
|
---|
| 84 | </indexterm>
|
---|
| 85 | <indexterm>
|
---|
| 86 | <primary>DITA</primary>
|
---|
| 87 | <secondary>htmlsearch plugin</secondary>
|
---|
| 88 | </indexterm></para>
|
---|
| 89 | </listitem>
|
---|
| 90 | <listitem>
|
---|
| 91 | <para>Stemmers from the <ulink
|
---|
| 92 | url="http://snowball.tartarus.org/texts/stemmersoverview.html">Snowball
|
---|
| 93 | project</ulink> released under a BSD license.</para>
|
---|
| 94 | </listitem>
|
---|
| 95 | <listitem>
|
---|
| 96 | <para>Code from the <ulink url="http://lucene.apache.org/">Apache Lucene</ulink> search
|
---|
| 97 | engine provides support for tokenizing Chinese, Japanese, and Korean content released
|
---|
| 98 | under the Apache 2.0 license. </para>
|
---|
| 99 | </listitem>
|
---|
| 100 | <listitem>
|
---|
| 101 | <para>Code that provides weighted search results and some
|
---|
| 102 | other improvements was graciously donated by <ulink
|
---|
| 103 | url="http://www.oxygenxml.com">SyncRO Soft
|
---|
| 104 | Ltd.</ulink>, the publishers of the oXygen XML
|
---|
| 105 | Editor.</para>
|
---|
| 106 | </listitem>
|
---|
| 107 | <listitem>
|
---|
| 108 | <para><ulink url="http://ccil.org/~cowan/XML/tagsoup/"
|
---|
| 109 | >TagSoup</ulink>, released under the Apache 2.0
|
---|
| 110 | license, makes it possible to index html instead of just
|
---|
| 111 | xhtml output. </para>
|
---|
| 112 | </listitem>
|
---|
| 113 | <listitem>
|
---|
| 114 | <para>Cosmetic improvements provided by <ulink
|
---|
| 115 | url="http://docs.openstack.org"
|
---|
| 116 | >OpenStack</ulink>.</para>
|
---|
| 117 | </listitem>
|
---|
| 118 | </itemizedlist> Webhelp for DocBook was first developed as a <ulink
|
---|
| 119 | url="http://code.google.com/soc/">Google Summer of Code</ulink> project. </para>
|
---|
| 120 | </legalnotice>
|
---|
| 121 | <copyright>
|
---|
| 122 | <year>2008-2012</year>
|
---|
| 123 | <holder>Kasun Gajasinghe</holder>
|
---|
| 124 | <holder>David Cramer</holder>
|
---|
| 125 | </copyright>
|
---|
| 126 | <author>
|
---|
| 127 | <firstname>David</firstname>
|
---|
| 128 | <surname>Cramer</surname>
|
---|
| 129 | <email>david AT thingbag DOT net</email>
|
---|
| 130 | </author>
|
---|
| 131 | <author>
|
---|
| 132 | <firstname>Kasun</firstname>
|
---|
| 133 | <surname>Gajasinghe</surname>
|
---|
| 134 | <email>kasunbg AT gmail DOT com</email>
|
---|
| 135 | </author>
|
---|
| 136 | <pubdate>January 2012</pubdate>
|
---|
| 137 | </bookinfo>
|
---|
| 138 | <chapter>
|
---|
| 139 | <chapterinfo>
|
---|
| 140 | <abstract>
|
---|
| 141 | <!-- This becomes the brief description that appears in search results UNLESS there's a para or phrase with role="summary". If there is, then the role="summary" text wins. -->
|
---|
| 142 | <para>Overview of the package.</para>
|
---|
| 143 | </abstract>
|
---|
| 144 | </chapterinfo>
|
---|
| 145 | <title>Introduction</title>
|
---|
| 146 | <para>A common requirement for technical publications groups is to produce a Web-based help
|
---|
| 147 | format that includes a table of contents pane, a search feature, and an index similar to what
|
---|
| 148 | you get from the Microsoft HTML Help (.chm) format or Eclipse help. If the content is help for
|
---|
| 149 | a Web application that is not exposed to the Internet or requires that the user be logged in,
|
---|
| 150 | then it is impossible to use services like Google to add search. <indexterm class="singular">
|
---|
| 151 | <primary>features</primary>
|
---|
| 152 | </indexterm>
|
---|
| 153 | <itemizedlist>
|
---|
| 154 | <title>Features</title>
|
---|
| 155 | <listitem>
|
---|
| 156 | <para>Sophisticated CSS-based page layout</para>
|
---|
| 157 | </listitem>
|
---|
| 158 | <listitem>
|
---|
| 159 | <para>Client-side search.<indexterm class="singular">
|
---|
| 160 | <primary>search</primary>
|
---|
| 161 | <secondary>features</secondary>
|
---|
| 162 | </indexterm></para>
|
---|
| 163 | <itemizedlist>
|
---|
| 164 | <listitem>
|
---|
| 165 | <para>Provides full content search of the documentation. Shows the search results with
|
---|
| 166 | links to chunked pages, and a small description.</para>
|
---|
| 167 | </listitem>
|
---|
| 168 | <listitem>
|
---|
| 169 | <para>Search results scoring/rating - The results are weighted according to how many
|
---|
| 170 | times the words in search query appears in it, is it bold or not, is in index terms
|
---|
| 171 | etc. The score out of 5 is shown by small colored boxes after each
|
---|
| 172 | search-result.</para>
|
---|
| 173 | </listitem>
|
---|
| 174 | <listitem>
|
---|
| 175 | <para>Search results can include brief descriptions of the target.<indexterm
|
---|
| 176 | class="singular">
|
---|
| 177 | <primary>search</primary>
|
---|
| 178 | <secondary>description</secondary>
|
---|
| 179 | </indexterm></para>
|
---|
| 180 | </listitem>
|
---|
| 181 | <listitem>
|
---|
| 182 | <para>Stemming support for English, French, and German. Stemming support can be added
|
---|
| 183 | for other languages by implementing a stemmer.<indexterm class="singular">
|
---|
| 184 | <primary>search</primary>
|
---|
| 185 | <secondary>stemming</secondary>
|
---|
| 186 | </indexterm></para>
|
---|
| 187 | </listitem>
|
---|
| 188 | <listitem>
|
---|
| 189 | <para>Support for Chinese, Japanese, and Korean languages using code from the Lucene search
|
---|
| 190 | engine.</para>
|
---|
| 191 | </listitem>
|
---|
| 192 | <listitem>
|
---|
| 193 | <para>Search highlighting shows where the searched term appears in the results.
|
---|
| 194 | <indexterm class="singular">
|
---|
| 195 | <primary>search</primary>
|
---|
| 196 | <secondary>highlighting</secondary>
|
---|
| 197 | </indexterm></para>
|
---|
| 198 | </listitem>
|
---|
| 199 | </itemizedlist>
|
---|
| 200 | </listitem>
|
---|
| 201 | <listitem>
|
---|
| 202 | <para>Table of contents (TOC) pane with collapsible toc tree.</para>
|
---|
| 203 | </listitem>
|
---|
| 204 | <listitem>
|
---|
| 205 | <para>Auto-synchronization of content pane and TOC.</para>
|
---|
| 206 | </listitem>
|
---|
| 207 | <listitem>
|
---|
| 208 | <para>Nicely placed small forward, backward, top links</para>
|
---|
| 209 | </listitem>
|
---|
| 210 | <listitem>
|
---|
| 211 | <para>TOC and search pane implemented without the use of a frameset.</para>
|
---|
| 212 | </listitem>
|
---|
| 213 | <listitem>
|
---|
| 214 | <para>An Ant script and sample Makefile to generate output.
|
---|
| 215 | You can use the ant build file by importing it into your
|
---|
| 216 | own or use it as a model for integrating this output
|
---|
| 217 | format into your own build system. Alternatively, you can
|
---|
| 218 | use the build scripts as a template for creating your own
|
---|
| 219 | script. You can also generate webhelp from DocBook using
|
---|
| 220 | the <ulink
|
---|
| 221 | url="http://docbkx-tools.sourceforge.net/docbkx-samples/manual.html"
|
---|
| 222 | >Docbkx Maven plugin</ulink>.</para>
|
---|
| 223 | </listitem>
|
---|
| 224 | </itemizedlist></para>
|
---|
| 225 | </chapter>
|
---|
| 226 | <chapter>
|
---|
| 227 | <title>Using the package</title>
|
---|
| 228 | <para role="summary">The following sections describe how to
|
---|
| 229 | install and use the package on Windows with the sample Ant build
|
---|
| 230 | script. In an environment where unix shell command are
|
---|
| 231 | available, you can also use the
|
---|
| 232 | <filename>Makefile.sample</filename> as a starting point for
|
---|
| 233 | creating your build script. To use
|
---|
| 234 | <filename>Makefile.sample</filename> you must have
|
---|
| 235 | <command>xsltproc</command> and <command>java</command>
|
---|
| 236 | available in your <envar>PATH</envar>.</para>
|
---|
| 237 | <section>
|
---|
| 238 | <sectioninfo>
|
---|
| 239 | <abstract>
|
---|
| 240 | <para>Installation instructions</para>
|
---|
| 241 | </abstract>
|
---|
| 242 | </sectioninfo>
|
---|
| 243 | <title>Generating webhelp output using the Ant build.xml
|
---|
| 244 | file</title>
|
---|
| 245 | <procedure>
|
---|
| 246 | <title>To install the package</title>
|
---|
| 247 | <note>
|
---|
| 248 | <para>The examples in this procedure assume a Windows
|
---|
| 249 | installation, but the process is the same in other
|
---|
| 250 | environments, <foreignphrase>mutatis
|
---|
| 251 | mutandis</foreignphrase>. In an environment where unix
|
---|
| 252 | shell command are available, you can also use the
|
---|
| 253 | <filename>Makefile.sample</filename> as a starting point
|
---|
| 254 | for creating your build script. To use
|
---|
| 255 | <filename>Makefile.sample</filename> you must have
|
---|
| 256 | <command>xsltproc</command> and <command>java</command>
|
---|
| 257 | available in your <envar>PATH</envar>. You can also use
|
---|
| 258 | the <ulink
|
---|
| 259 | url="http://docbkx-tools.sourceforge.net/docbkx-samples/manual.html"
|
---|
| 260 | >Docbkx Maven plugin</ulink> to generate webhelp.</para>
|
---|
| 261 | </note>
|
---|
| 262 | <step>
|
---|
| 263 | <para>If necessary, install <ulink url="http://www.java.com/en/download/manual.jsp">Java
|
---|
| 264 | 1.6</ulink> or higher.</para>
|
---|
| 265 | <substeps>
|
---|
| 266 | <step>
|
---|
| 267 | <para>Confirm that Java is installed and in your <envar>PATH</envar> by typing the
|
---|
| 268 | following at a command prompt: <programlisting>java -version</programlisting></para>
|
---|
| 269 | <note>
|
---|
| 270 | <para>To build the indexer, you must have the JDK.</para>
|
---|
| 271 | </note>
|
---|
| 272 | </step>
|
---|
| 273 | </substeps>
|
---|
| 274 | </step>
|
---|
| 275 | <step>
|
---|
| 276 | <para>If necessary, install <ulink url="http://ant.apache.org/bindownload.cgi">Apache
|
---|
| 277 | Ant</ulink> 1.8.0 or higher. See <ulink
|
---|
| 278 | url="http://ant.apache.org/manual/install.html">Ant installation instructions</ulink>.</para>
|
---|
| 279 | <substeps>
|
---|
| 280 | <step>
|
---|
| 281 | <para>Unzip the Ant binary distribution to a convenient location on your system. For
|
---|
| 282 | example: <filename>c:\Program Files</filename>.</para>
|
---|
| 283 | </step>
|
---|
| 284 | <step>
|
---|
| 285 | <para>Set the environment variable <envar>ANT_HOME</envar> to the top-level Ant
|
---|
| 286 | directory. For example: <filename>c:\Program Files\apache-ant-1.8.0</filename>. <tip>
|
---|
| 287 | <para>See <ulink url="http://support.microsoft.com/kb/310519">How To Manage
|
---|
| 288 | Environment Variables in Windows XP</ulink> for information on setting
|
---|
| 289 | environment variables.</para>
|
---|
| 290 | </tip></para>
|
---|
| 291 | </step>
|
---|
| 292 | <step>
|
---|
| 293 | <para>Add the Ant <filename>bin</filename> directory to your <envar>PATH</envar>. For
|
---|
| 294 | example: <filename>c:\Program Files\apache-ant-1.8.0\bin</filename></para>
|
---|
| 295 | </step>
|
---|
| 296 | <step>
|
---|
| 297 | <para>Confirm that Ant is installed by typing the following at a command prompt:
|
---|
| 298 | <programlisting>ant -version</programlisting></para>
|
---|
| 299 | <note>
|
---|
| 300 | <para>If you see a message about the file <filename>tools.jar</filename> being
|
---|
| 301 | missing, you can safely ignore it.</para>
|
---|
| 302 | </note>
|
---|
| 303 | </step>
|
---|
| 304 | </substeps>
|
---|
| 305 | </step>
|
---|
| 306 | <step>
|
---|
| 307 | <para>Download <ulink url="http://prdownloads.sourceforge.net/saxon/saxon6-5-5.zip">Saxon
|
---|
| 308 | 6.5.x</ulink> and unzip the distribution to a convenient location on your file system.
|
---|
| 309 | You will use the path to <filename>saxon.jar</filename> in <xref
|
---|
| 310 | linkend="edit-build-properties"/> below.<note>
|
---|
| 311 | <para>The <filename>build.xml</filename> has only been tested with Saxon 6.5, though
|
---|
| 312 | it could be adapted to work with other XSLT processors. However, when you generate
|
---|
| 313 | output, the Saxon jar must <emphasis role="bold">not</emphasis> be in your
|
---|
| 314 | <envar>CLASSPATH</envar>.</para>
|
---|
| 315 | </note></para>
|
---|
| 316 | </step>
|
---|
| 317 | <step>
|
---|
| 318 | <para>Download <ulink
|
---|
| 319 | url="https://xerces.apache.org/xerces2-j/">Xerces2
|
---|
| 320 | Java</ulink> and extract it to a convenient location on
|
---|
| 321 | your file system. You will need the
|
---|
| 322 | <filename>xercesImpl.jar</filename> and
|
---|
| 323 | <filename>xml-apis.jar</filename> from this distribution
|
---|
| 324 | in in <xref linkend="edit-build-properties"/>. </para>
|
---|
| 325 | </step>
|
---|
| 326 | <step id="edit-build-properties">
|
---|
| 327 | <para>In a text editor, edit the
|
---|
| 328 | <filename>build.properties</filename> file in the
|
---|
| 329 | webhelp directory and make the changes indicated by the comments.<important>
|
---|
| 330 | <para>You must set appropriate values for
|
---|
| 331 | <code>xslt-processor-classpath</code>,
|
---|
| 332 | <code>xercesImpl.jar</code>, and
|
---|
| 333 | <code>xml-apis.jar</code>.</para>
|
---|
| 334 | </important>See the DocBook <ulink
|
---|
| 335 | url="../../../doc/html/webhelp.html">reference
|
---|
| 336 | documentation</ulink> for detailed information about the
|
---|
| 337 | available webhelp and other parameters. Note that not all
|
---|
| 338 | DocBook parameters are passed in to the xsls by the
|
---|
| 339 | <filename>build.xml</filename> by default. You may need
|
---|
| 340 | to modify the <filename>build.xml</filename> to pass in
|
---|
| 341 | some DocBook
|
---|
| 342 | parameters.<programlisting>
|
---|
| 343 | # The path (relative to the build.xml file) to your input document.
|
---|
| 344 | # To use your own input document, create a build.xml file of your own
|
---|
| 345 | # and import this build.xml.
|
---|
| 346 | input-xml=docsrc/readme.xml
|
---|
| 347 |
|
---|
| 348 | # The directory in which to put the output files.
|
---|
| 349 | # This directory is created if it does not exist.
|
---|
| 350 | output-dir=docs
|
---|
| 351 |
|
---|
| 352 | # If you are using a customization layer that imports webhelp.xsl, use
|
---|
| 353 | # this property to point to it.
|
---|
| 354 | stylesheet-path=${ant.file.dir}/xsl/webhelp.xsl
|
---|
| 355 |
|
---|
| 356 | # If your document has image directories that need to be copied
|
---|
| 357 | # to the output directory, you can list patterns here.
|
---|
| 358 | # See the Ant documentation for fileset for documentation
|
---|
| 359 | # on patterns.
|
---|
| 360 | #input-images-dirs=images/**,figures/**,graphics/**
|
---|
| 361 |
|
---|
| 362 | # By default, the ant script assumes your images are stored
|
---|
| 363 | # in the same directory as the input-xml. If you store your
|
---|
| 364 | # image directories in another directory, specify it here.
|
---|
| 365 | # and uncomment this line.
|
---|
| 366 | #input-images-basedir=/path/to/image/location
|
---|
| 367 |
|
---|
| 368 | <emphasis># Modify the follosing so that they point to your local
|
---|
| 369 | # copy of the jars indicated:
|
---|
| 370 | # * Saxon 6.5 jar
|
---|
| 371 | # * Xerces 2: xercesImpl.jar
|
---|
| 372 | # * xml-commons: xml-apis.jar
|
---|
| 373 | xslt-processor-classpath=/usr/share/java/saxon-6.5.5.jar
|
---|
| 374 | xercesImpl.jar=/usr/share/java/xercesImpl.jar
|
---|
| 375 | xml-apis.jar=/usr/share/java/xml-apis.jar
|
---|
| 376 | </emphasis>
|
---|
| 377 | # For non-ns version only, this validates the document
|
---|
| 378 | # against a dtd.
|
---|
| 379 | validate-against-dtd=true
|
---|
| 380 |
|
---|
| 381 | # The extension for files to be indexed (html/htm/xhtml etc.)
|
---|
| 382 | html.extension=html
|
---|
| 383 |
|
---|
| 384 | # Set this to false if you don't need a search tab.
|
---|
| 385 | webhelp.include.search.tab=true
|
---|
| 386 |
|
---|
| 387 | # indexer-language is used to tell the search indexer which language
|
---|
| 388 | # the docbook is written. This will be used to identify the correct
|
---|
| 389 | # stemmer, and punctuations that differs from language to language.
|
---|
| 390 | # see the documentation for details. en=English, fr=French, de=German,
|
---|
| 391 | # zh=Chinese, ja=Japanese etc.
|
---|
| 392 | webhelp.indexer.language=en
|
---|
| 393 |
|
---|
| 394 | # Enables/Disables stemming
|
---|
| 395 | # Stemming allows better querying for the search
|
---|
| 396 | enable.stemming=true
|
---|
| 397 |
|
---|
| 398 | # Set admon.graphics to 1 to user graphics for note, tip, etc.
|
---|
| 399 | admon.graphics=0
|
---|
| 400 | suppress.footer.navigation=0</programlisting></para>
|
---|
| 401 | </step>
|
---|
| 402 | <step>
|
---|
| 403 | <para>Test the package by running the command <code>ant
|
---|
| 404 | webhelp -Doutput-dir=test-ouput</code> at the command
|
---|
| 405 | line in the webhelp directory. It should generate a copy
|
---|
| 406 | of this documentation in the <filename class="directory"
|
---|
| 407 | >doc</filename> directory. Type <code>start
|
---|
| 408 | test-output\index.html</code> to open the output in a
|
---|
| 409 | browser. Once you have confirmed that the process worked,
|
---|
| 410 | you can delete the <filename class="directory"
|
---|
| 411 | >test-output</filename> directory. </para>
|
---|
| 412 | </step>
|
---|
| 413 | <step>
|
---|
| 414 | <para>To process your own document, simply refer to this package from another
|
---|
| 415 | <filename>build.xml</filename> in arbitrary location on your system:</para>
|
---|
| 416 | <substeps>
|
---|
| 417 | <step>
|
---|
| 418 | <para>Create a new <filename>build.xml</filename> file that defines the name of your
|
---|
| 419 | source file, the desired output directory, and imports the
|
---|
| 420 | <filename>build.xml</filename> from this package. For example:
|
---|
| 421 | <programlisting><project>
|
---|
| 422 | <property name="input-xml" value="<replaceable>path-to/yourfile.xml</replaceable>"/>
|
---|
| 423 | <property name="input-images-dirs" value="<replaceable>images/** figures/** graphics/**</replaceable>"/>
|
---|
| 424 | <property name="output-dir" value="<replaceable>path-to/desired-output-dir</replaceable>"/>
|
---|
| 425 | <import file="<replaceable>path-to/docbook-webhelp/</replaceable>build.xml"/>
|
---|
| 426 | </project></programlisting></para>
|
---|
| 427 | </step>
|
---|
| 428 | <step>
|
---|
| 429 | <para>From the directory containing your newly created <filename>build.xml</filename>
|
---|
| 430 | file, type <code>ant webhelp</code> to build your document.</para>
|
---|
| 431 | </step>
|
---|
| 432 | </substeps>
|
---|
| 433 | </step>
|
---|
| 434 | </procedure>
|
---|
| 435 | </section>
|
---|
| 436 | <section>
|
---|
| 437 | <title>Using and customizing the output</title>
|
---|
| 438 | <para>To deep link to a topic inside the help set, simply link directly to the page. This help
|
---|
| 439 | system uses no frameset, so nothing further is necessary. <tip>
|
---|
| 440 | <para>See <ulink url="http://www.sagehill.net/docbookxsl/Chunking.html">Chunking into
|
---|
| 441 | multiple HTML files</ulink> in Bob Stayton's <ulink
|
---|
| 442 | url="http://www.sagehill.net/docbookxsl/index.html">DocBook XSL: The Complete
|
---|
| 443 | Guide</ulink> for information on controlling output file names and which files are
|
---|
| 444 | chunked in DocBook.</para>
|
---|
| 445 | </tip></para>
|
---|
| 446 | <para>When you perform a search, the results can include brief summaries. These are populated
|
---|
| 447 | in one of two ways:<itemizedlist>
|
---|
| 448 | <listitem>
|
---|
| 449 | <para>By adding <sgmltag>role="summary"</sgmltag> to a <sgmltag>para</sgmltag> or
|
---|
| 450 | <sgmltag>phrase</sgmltag> in the <sgmltag>chapter</sgmltag> or
|
---|
| 451 | <sgmltag>section</sgmltag>.</para>
|
---|
| 452 | </listitem>
|
---|
| 453 | <listitem>
|
---|
| 454 | <para>By adding an <sgmltag>abstract</sgmltag> to the <sgmltag>chapterinfo</sgmltag> or
|
---|
| 455 | <sgmltag>sectioninfo</sgmltag> element.</para>
|
---|
| 456 | </listitem>
|
---|
| 457 | </itemizedlist></para>
|
---|
| 458 | <para>To customize the look and feel of the help, study the following css files:<itemizedlist>
|
---|
| 459 | <listitem>
|
---|
| 460 | <para><filename>docs/common/css/positioning.css</filename>: This handles the Positioning
|
---|
| 461 | of DIVs in appropriate positions. For example, it causes the
|
---|
| 462 | <code>leftnavigation</code> div to appear on the left, the header on top, and so on.
|
---|
| 463 | Use this if you need to change the relative positions or need to change the
|
---|
| 464 | width/height etc.</para>
|
---|
| 465 | </listitem>
|
---|
| 466 | <listitem>
|
---|
| 467 | <para><filename>docs/common/jquery/theme-redmond/jquery-ui-1.8.2.custom.css</filename>:
|
---|
| 468 | This is the theming part which adds colors and stuff. This is a default theme comes
|
---|
| 469 | with <ulink url="http://jqueryui.com/download">jqueryui</ulink> unchanged. You can get
|
---|
| 470 | any theme based your interest from this. (Themes are on right navigation bar.) Then
|
---|
| 471 | replace the css theme folder (theme-redmond) with it, and change the xsl to point to
|
---|
| 472 | the new css.</para>
|
---|
| 473 | </listitem>
|
---|
| 474 | <listitem>
|
---|
| 475 | <para><filename>docs/common/jquery/treeview/jquery.treeview.css</filename>: This styles
|
---|
| 476 | the toc Tree. Generally, you don't have to edit this file.</para>
|
---|
| 477 | </listitem>
|
---|
| 478 | </itemizedlist></para>
|
---|
| 479 | <section>
|
---|
| 480 | <title>Recommended Apache configurations</title>
|
---|
| 481 | <para>If you are serving a long document from an Apache web
|
---|
| 482 | server, we recommend you make the following additions or
|
---|
| 483 | changes to your <filename>httpd.conf</filename> or
|
---|
| 484 | <filename>.htaccess</filename> file. <programlisting>AddDefaultCharSet UTF-8 # <co id="AddDefaultCharSet"/>
|
---|
| 485 |
|
---|
| 486 | # 480 weeks
|
---|
| 487 | <FilesMatch "\.(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$"> # <co id="CachingSettings"/>
|
---|
| 488 | Header set Cache-Control "max-age=290304000, public"
|
---|
| 489 | </FilesMatch>
|
---|
| 490 |
|
---|
| 491 | # 2 DAYS
|
---|
| 492 | <FilesMatch "\.(xml|txt)$">
|
---|
| 493 | Header set Cache-Control "max-age=172800, public, must-revalidate"
|
---|
| 494 | </FilesMatch>
|
---|
| 495 |
|
---|
| 496 | # 2 HOURS
|
---|
| 497 | <FilesMatch "\.(html|htm)$">
|
---|
| 498 | Header set Cache-Control "max-age=7200, must-revalidate"
|
---|
| 499 | </FilesMatch>
|
---|
| 500 |
|
---|
| 501 | # compress text, html, javascript, css, xml:
|
---|
| 502 | AddOutputFilterByType DEFLATE text/plain # <co id="CompressSetting"/>
|
---|
| 503 | AddOutputFilterByType DEFLATE text/html
|
---|
| 504 | AddOutputFilterByType DEFLATE text/xml
|
---|
| 505 | AddOutputFilterByType DEFLATE text/css
|
---|
| 506 | AddOutputFilterByType DEFLATE application/xml
|
---|
| 507 | AddOutputFilterByType DEFLATE application/xhtml+xml
|
---|
| 508 | AddOutputFilterByType DEFLATE application/rss+xml
|
---|
| 509 | AddOutputFilterByType DEFLATE application/javascript
|
---|
| 510 | AddOutputFilterByType DEFLATE application/x-javascript
|
---|
| 511 |
|
---|
| 512 | # Or, compress certain file types by extension:
|
---|
| 513 | <Files *.html>
|
---|
| 514 | SetOutputFilter DEFLATE
|
---|
| 515 | </Files>
|
---|
| 516 | </programlisting><calloutlist>
|
---|
| 517 | <callout arearefs="AddDefaultCharSet">
|
---|
| 518 | <para>See <ulink
|
---|
| 519 | url="http://www.sagehill.net/docbookxsl/SpecialChars.html"
|
---|
| 520 | >Odd characters in HTML output</ulink> in Bob
|
---|
| 521 | Stayton's book <citetitle>DocBook XSL: The Complete
|
---|
| 522 | Guide</citetitle> for more information about this
|
---|
| 523 | setting.</para>
|
---|
| 524 | </callout>
|
---|
| 525 | <callout arearefs="CachingSettings">
|
---|
| 526 | <para>These lines and those that follow cause the
|
---|
| 527 | browser to cache various resources such as bitmaps and
|
---|
| 528 | JavaScript files. Note that caching JavaScript files
|
---|
| 529 | could cause your users to have stale search indexes if
|
---|
| 530 | you update your document since the search index is
|
---|
| 531 | stored in JavaScript files.</para>
|
---|
| 532 | </callout>
|
---|
| 533 | <callout arearefs="CompressSetting">
|
---|
| 534 | <para>These lines cause the the server to compress html,
|
---|
| 535 | css, and JavaScript files and the brower to uncompress
|
---|
| 536 | them to improve download performance.</para>
|
---|
| 537 | </callout>
|
---|
| 538 | </calloutlist></para>
|
---|
| 539 | </section>
|
---|
| 540 | </section>
|
---|
| 541 | <section>
|
---|
| 542 | <title>Search indexing</title>
|
---|
| 543 | <para>Run <command>ant index</command> in the webhelp directory to index the content. Running
|
---|
| 544 | <command>ant webhelp</command> will do the indexing as part of the process as well.</para>
|
---|
| 545 | <para>Here's some detailed information about invoking the indexer. The indexing process is
|
---|
| 546 | pretty smooth, so probably you doesn't need to be concerned with following details. Webhelp
|
---|
| 547 | Ant script does all the needed bits.</para>
|
---|
| 548 | <itemizedlist>
|
---|
| 549 | <listitem>
|
---|
| 550 | <para>Following should be in the CLASSPATH.</para>
|
---|
| 551 | <para>
|
---|
| 552 | <itemizedlist>
|
---|
| 553 | <listitem>
|
---|
| 554 | <para><filename>webhelpindexer.jar</filename>,
|
---|
| 555 | <filename>lucene-analyzers-3.0.0.jar</filename>,
|
---|
| 556 | <filename>lucene-core-3.0.0.jar</filename> - These three are available in the
|
---|
| 557 | extensions/ directory of docsbook-xsl-1.76.1, and is automatically fetched to the
|
---|
| 558 | webhelp's Ant script. Go for a XSL snapshot if you can which contains the latest
|
---|
| 559 | version http://docbook.sourceforge.net/snapshot/</para>
|
---|
| 560 | </listitem>
|
---|
| 561 | <listitem>
|
---|
| 562 | <para><filename>xercesImpl.jar</filename>, <filename> xml-apis.jar</filename> -
|
---|
| 563 | These two comes by default with Ant 1.8.0 or prior versions. These are available
|
---|
| 564 | under /usr/share/java directory of Linux distributions as well. Else, you may have
|
---|
| 565 | to download, and put them to <filename>jre/lib/endorsed</filename>.</para>
|
---|
| 566 | </listitem>
|
---|
| 567 | </itemizedlist>
|
---|
| 568 | </para>
|
---|
| 569 | </listitem>
|
---|
| 570 | <listitem>
|
---|
| 571 | <para>The main class is <classname>com.nexwave.nquindexer.IndexerMain</classname> for the
|
---|
| 572 | version 1.76.1+. It's <classname>com.nexwave.nquindexer.IndexerTask</classname> for the
|
---|
| 573 | versions 1.76.0 and 1.76.1.</para>
|
---|
| 574 | <para>
|
---|
| 575 | <itemizedlist>
|
---|
| 576 | <listitem>
|
---|
| 577 | <para>Needs two parameters as command-line arguments:</para>
|
---|
| 578 | <para>
|
---|
| 579 | <itemizedlist>
|
---|
| 580 | <listitem>
|
---|
| 581 | <para>The folder where the files to be indexed reside</para>
|
---|
| 582 | </listitem>
|
---|
| 583 | </itemizedlist>
|
---|
| 584 | <itemizedlist>
|
---|
| 585 | <listitem>
|
---|
| 586 | <para>(Optional) language. defaults to "en". See build.properties for
|
---|
| 587 | details</para>
|
---|
| 588 | </listitem>
|
---|
| 589 | </itemizedlist>
|
---|
| 590 | </para>
|
---|
| 591 | </listitem>
|
---|
| 592 | </itemizedlist>
|
---|
| 593 | <note>
|
---|
| 594 | <para>We have changed the way we invoke the webhelp indexer from the Ant Task to
|
---|
| 595 | <code>indexertask</code> to direct invocation. This seems to have remove the
|
---|
| 596 | <envar>CLASSPATH</envar> issue some people were having.</para>
|
---|
| 597 | </note>
|
---|
| 598 | </para>
|
---|
| 599 | </listitem>
|
---|
| 600 | </itemizedlist>
|
---|
| 601 | <indexterm>
|
---|
| 602 | <primary>search</primary>
|
---|
| 603 | <secondary>indexing</secondary>
|
---|
| 604 | </indexterm>
|
---|
| 605 | <indexterm>
|
---|
| 606 | <primary>indexer</primary>
|
---|
| 607 | <secondary>CLASSPATH</secondary>
|
---|
| 608 | </indexterm>
|
---|
| 609 | <para role="summary">To build the indexer, you must have installed the JDK version 1.5 or
|
---|
| 610 | higher and set the <envar>ANT_HOME</envar> environment variable. </para>
|
---|
| 611 | <indexterm>
|
---|
| 612 | <primary>ANT_HOME</primary>
|
---|
| 613 | </indexterm>
|
---|
| 614 | <indexterm>
|
---|
| 615 | <primary>indexer</primary>
|
---|
| 616 | <secondary>building</secondary>
|
---|
| 617 | </indexterm>
|
---|
| 618 | </section>
|
---|
| 619 | <section>
|
---|
| 620 | <title>Adding support for other (non-CJKV) languages</title>
|
---|
| 621 | <para>To support stemming for a language, the search mechanism requires a stemmer implemented
|
---|
| 622 | in both Java and JavaScript. The Java version is used by the indexer and the JavaScript
|
---|
| 623 | verison is used to stem the user's input on the search form. Currently the search mechanism
|
---|
| 624 | supports stemming for English and German. In addition, Java stemmers are included for the
|
---|
| 625 | following languages. Therefore, to support these languages, you only need to implement the
|
---|
| 626 | stemmer in JavaScript and add it to the template. If you do undertake this task, please
|
---|
| 627 | consider contributing the JavaScript version back to this project and to <ulink
|
---|
| 628 | url="http://snowball.tartarus.org/texts/stemmersoverview.html">Martin Porter's
|
---|
| 629 | project</ulink>.<itemizedlist>
|
---|
| 630 | <listitem>
|
---|
| 631 | <para>Danish</para>
|
---|
| 632 | </listitem>
|
---|
| 633 | <listitem>
|
---|
| 634 | <para>Dutch</para>
|
---|
| 635 | </listitem>
|
---|
| 636 | <listitem>
|
---|
| 637 | <para>Finnish</para>
|
---|
| 638 | </listitem>
|
---|
| 639 | <listitem>
|
---|
| 640 | <para>Hungarian</para>
|
---|
| 641 | </listitem>
|
---|
| 642 | <listitem>
|
---|
| 643 | <para>Italian</para>
|
---|
| 644 | </listitem>
|
---|
| 645 | <listitem>
|
---|
| 646 | <para>Norwegian</para>
|
---|
| 647 | </listitem>
|
---|
| 648 | <listitem>
|
---|
| 649 | <para>Portuguese</para>
|
---|
| 650 | </listitem>
|
---|
| 651 | <listitem>
|
---|
| 652 | <para>Romanian</para>
|
---|
| 653 | </listitem>
|
---|
| 654 | <listitem>
|
---|
| 655 | <para>Russian</para>
|
---|
| 656 | </listitem>
|
---|
| 657 | <listitem>
|
---|
| 658 | <para>Spanish</para>
|
---|
| 659 | </listitem>
|
---|
| 660 | <listitem>
|
---|
| 661 | <para>Swedish</para>
|
---|
| 662 | </listitem>
|
---|
| 663 | <listitem>
|
---|
| 664 | <para>Turkish</para>
|
---|
| 665 | </listitem>
|
---|
| 666 | </itemizedlist><indexterm>
|
---|
| 667 | <primary>stemming</primary>
|
---|
| 668 | </indexterm></para>
|
---|
| 669 | </section>
|
---|
| 670 | <section>
|
---|
| 671 | <title>Adding images</title>
|
---|
| 672 | <para>This section shows how to add images to WebHelp. For that, follow the simple procedure given.<itemizedlist>
|
---|
| 673 | <listitem>
|
---|
| 674 | <para>Put the images in a subdirectory of your source file directory. For example
|
---|
| 675 | <filename>docsrc/images</filename>.</para>
|
---|
| 676 | </listitem>
|
---|
| 677 | <listitem>
|
---|
| 678 | <para>Then refer to those images from your docbook document.</para>
|
---|
| 679 | <para>Following image is from <emphasis role="bold"
|
---|
| 680 | >webhelp/docsrs/images/sample.jpg</emphasis>. The docbook code is shown
|
---|
| 681 | below.</para>
|
---|
| 682 | <para>
|
---|
| 683 | <figure>
|
---|
| 684 | <title>Sample Image</title>
|
---|
| 685 | <mediaobject>
|
---|
| 686 | <imageobject>
|
---|
| 687 | <imagedata fileref="images/sample.jpg" format="JPG"/>
|
---|
| 688 | </imageobject>
|
---|
| 689 | </mediaobject>
|
---|
| 690 | </figure>
|
---|
| 691 | </para>
|
---|
| 692 | <example>
|
---|
| 693 | <title>Example code for adding images. Note down the relative path used</title>
|
---|
| 694 | <programlisting><figure>
|
---|
| 695 | <title>Sample</title>
|
---|
| 696 | <mediaobject>
|
---|
| 697 | <imageobject>
|
---|
| 698 | <imagedata fileref="<emphasis role="bold">images/sample.jpg</emphasis>" format="JPG"/>
|
---|
| 699 | </imageobject>
|
---|
| 700 | </mediaobject>
|
---|
| 701 | </figure></programlisting>
|
---|
| 702 | </example>
|
---|
| 703 | </listitem>
|
---|
| 704 | <listitem>
|
---|
| 705 | <para> The <filename>build.properties</filename> file controls what directories are copied
|
---|
| 706 | over from the source tree to the output
|
---|
| 707 | tree:<programlisting># If your document has image directories that need to be copied
|
---|
| 708 | # to the output directory, you can list patterns here.
|
---|
| 709 | # See the Ant documentation for fileset for documentation
|
---|
| 710 | # on patterns.
|
---|
| 711 | input-images-dirs=images/**,figures/**,graphics/**</programlisting></para>
|
---|
| 712 | </listitem>
|
---|
| 713 | </itemizedlist></para>
|
---|
| 714 | </section>
|
---|
| 715 | </chapter>
|
---|
| 716 | <chapter>
|
---|
| 717 | <title>Developer Docs</title>
|
---|
| 718 | <para role="summary">This chapter provides an overview of how webhelp is implemented.</para>
|
---|
| 719 | <para>The table of contents and search panes are implemented as divs and rendered as if they
|
---|
| 720 | were the left pane in a frameset. As a result, the page must save the state of the table of
|
---|
| 721 | contents and the search in cookies when you navigate away from a page. When you load a new
|
---|
| 722 | page, the page reads these cookies and restores the state of the table of contents tree and
|
---|
| 723 | search. The result is that the help system behaves exactly as if it were a frameset.</para>
|
---|
| 724 | <section>
|
---|
| 725 | <title>Design</title>
|
---|
| 726 | <para role="summary">An overview of webhelp page structure.</para>
|
---|
| 727 | <para>DocBook WebHelp page structure is fully built on css-based design abandoning frameset
|
---|
| 728 | structure. Overall page structure can be divided in to three main sections <itemizedlist>
|
---|
| 729 | <listitem>
|
---|
| 730 | <para>Header: Header is a separate Div which include company logo, navigation
|
---|
| 731 | button(prev, next etc.), page title and heading of parent topic.</para>
|
---|
| 732 | </listitem>
|
---|
| 733 | <listitem>
|
---|
| 734 | <para>Content: This includes the content of the documentation. The processing of this
|
---|
| 735 | part is done by <ulink
|
---|
| 736 | url="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"> DocBook
|
---|
| 737 | XSL Chunking customization</ulink>. Few further css-styling applied from
|
---|
| 738 | <filename>positioning.css</filename>. </para>
|
---|
| 739 | </listitem>
|
---|
| 740 | <listitem>
|
---|
| 741 | <para>Left Navigation: This includes the table of contents and search tab. This is
|
---|
| 742 | customized using <ulink url="http://jqueryui.com/">jquery-ui</ulink> styling.</para>
|
---|
| 743 | <itemizedlist>
|
---|
| 744 | <listitem>
|
---|
| 745 | <para>Tabbed Navigation: The navigation pane is organized in to two tabs. Contents
|
---|
| 746 | tab, and Search tab. Tabbed output is achieved using <ulink
|
---|
| 747 | url="http://docs.jquery.com/UI/Tabs">JQuery Tabs plugin</ulink>. </para>
|
---|
| 748 | </listitem>
|
---|
| 749 | <listitem>
|
---|
| 750 | <para>Table of Contents (TOC) tree: When building the chunked html from the docbook
|
---|
| 751 | file, Table of Contents is generated as an Unordered List (a list made from
|
---|
| 752 | <code><ul> <li></code> tags). When page loads in the browser, we apply
|
---|
| 753 | styling to it to achieve the nice look that you see. Styling for TOC tree is done
|
---|
| 754 | by a JQuery UI plugin called <ulink
|
---|
| 755 | url="http://bassistance.de/jquery-plugins/jquery-plugin-treeview/">
|
---|
| 756 | TreeView</ulink>. We can generate the tree easily by following javascript code:
|
---|
| 757 | <programlisting>
|
---|
| 758 | //Generate the tree
|
---|
| 759 | $("#tree").treeview({
|
---|
| 760 | collapsed: true,
|
---|
| 761 | animated: "medium",
|
---|
| 762 | control: "#sidetreecontrol",
|
---|
| 763 | persist: "cookie"
|
---|
| 764 | });
|
---|
| 765 | </programlisting>
|
---|
| 766 | </para>
|
---|
| 767 | </listitem>
|
---|
| 768 | <listitem>
|
---|
| 769 | <para>Search Tab: This includes the search feature.</para>
|
---|
| 770 | </listitem>
|
---|
| 771 | </itemizedlist>
|
---|
| 772 | </listitem>
|
---|
| 773 | </itemizedlist>
|
---|
| 774 | <indexterm>
|
---|
| 775 | <primary>design</primary>
|
---|
| 776 | </indexterm></para>
|
---|
| 777 | </section>
|
---|
| 778 | <section>
|
---|
| 779 | <title>Search</title>
|
---|
| 780 | <para role="summary">Overview design of Search mechanism.</para>
|
---|
| 781 | <para>The serching is a fully client-side implementation of querying texts for content
|
---|
| 782 | searching. There's no server involved. So, the search queries by the users are processed by
|
---|
| 783 | JavaScript inside the browser, and displays the matching results by comparing the query with
|
---|
| 784 | a simplified 'index' that too resides in JavaScript. Mainly the search mechanism has two
|
---|
| 785 | parts. <itemizedlist>
|
---|
| 786 | <listitem>
|
---|
| 787 | <para>Indexing: First we need to traverse the content in
|
---|
| 788 | the docs folder and index the words in it. This is done
|
---|
| 789 | by <filename>webhelpindexer.jar</filename> in
|
---|
| 790 | <filename>xsl/extentions/</filename> folder. You can
|
---|
| 791 | invoke it by <code>ant index</code> command from the
|
---|
| 792 | root of webhelp of directory. The source of
|
---|
| 793 | webhelpindexer is now moved to it's own location at
|
---|
| 794 | <filename>trunk/xsl-webhelpindexer/</filename>.
|
---|
| 795 | Checkout the Docbook trunk svn directory to get this
|
---|
| 796 | source. Then, do your changes and recompile it by simply
|
---|
| 797 | running <code>ant</code> command. My assumption is that
|
---|
| 798 | it can be opened by Netbeans IDE by one click. Or if you
|
---|
| 799 | are using IntelliJ Idea, you can simply create a new
|
---|
| 800 | project from existing sources. Indexer has extensive
|
---|
| 801 | support for features such as word scoring, stemming of
|
---|
| 802 | words, and support for languages English, German,
|
---|
| 803 | French. For CJK (Chinese, Japanese, Korean) languages,
|
---|
| 804 | it uses bi-gram tokenizing to break up the words (since
|
---|
| 805 | CJK languages does not have spaces between
|
---|
| 806 | words).</para>
|
---|
| 807 | <para> When <code>ant index</code> is run, it generates five output files: <itemizedlist>
|
---|
| 808 | <listitem>
|
---|
| 809 | <para><filename>htmlFileList.js</filename> - This contains an array named
|
---|
| 810 | <code>fl</code> which stores details all the files indexed by the indexer.
|
---|
| 811 | Further, the doStem in it defines whether stemming should be used. It defaults
|
---|
| 812 | to false.</para>
|
---|
| 813 | </listitem>
|
---|
| 814 | <listitem>
|
---|
| 815 | <para><filename>htmlFileInfoList.js</filename> -
|
---|
| 816 | This includes some meta data about the indexed
|
---|
| 817 | files in an array named <code>fil</code>. It
|
---|
| 818 | includes details about file name, file (html)
|
---|
| 819 | title, a summary of the content. Format would look
|
---|
| 820 | like, <code>fil["4"]= "ch03.html@@@Developer
|
---|
| 821 | Docs@@@This chapter provides an overview of how
|
---|
| 822 | webhelp is implemented.";</code>
|
---|
| 823 | </para>
|
---|
| 824 | </listitem>
|
---|
| 825 | <listitem>
|
---|
| 826 | <para><filename>index-*.js</filename> (Three index files) - These three files
|
---|
| 827 | actually stores the index of the content. Index is added to an array named
|
---|
| 828 | <code>w</code>.</para>
|
---|
| 829 | </listitem>
|
---|
| 830 | </itemizedlist></para>
|
---|
| 831 | </listitem>
|
---|
| 832 | <listitem>
|
---|
| 833 | <para> Querying: Query processing happens totally in client side. Following JavaScript
|
---|
| 834 | files handles them. <itemizedlist>
|
---|
| 835 | <listitem>
|
---|
| 836 | <para><filename>nwSearchFnt.js</filename> - This handles the user query and
|
---|
| 837 | returns the search results. It does query word tokenizing, drop unnecessary
|
---|
| 838 | punctuations and common words, do stemming if docbook language supports it,
|
---|
| 839 | etc.</para>
|
---|
| 840 | </listitem>
|
---|
| 841 | <listitem>
|
---|
| 842 | <para><filename>{$indexer-language-code}_stemmer.js</filename> - This includes the
|
---|
| 843 | stemming library. <filename>nwSearchFnt.js</filename> file calls
|
---|
| 844 | <code>stemmer</code> method in this file for stemming. ex: <code>var stem =
|
---|
| 845 | stemmer(foobar);</code>
|
---|
| 846 | </para>
|
---|
| 847 | </listitem>
|
---|
| 848 | </itemizedlist>
|
---|
| 849 | </para>
|
---|
| 850 | </listitem>
|
---|
| 851 | </itemizedlist>
|
---|
| 852 | <indexterm>
|
---|
| 853 | <primary>search</primary>
|
---|
| 854 | </indexterm></para>
|
---|
| 855 | <section>
|
---|
| 856 | <title>New Stemmers</title>
|
---|
| 857 | <para role="summary">Adding new Stemmers is very simple.</para>
|
---|
| 858 | <para>Currently, only English, French, and German stemmers are integrated in to WebHelp. But
|
---|
| 859 | the code is extensible such that you can add new stemmers easily by few steps.</para>
|
---|
| 860 | <para>What you need: <itemizedlist>
|
---|
| 861 | <listitem>
|
---|
| 862 | <para>You'll need two versions of the stemmer; One written in JavaScript, and another
|
---|
| 863 | in Java. But fortunately, Snowball contains Java stemmers for number of popular
|
---|
| 864 | languages, and are already included with the package. You can see the full list in
|
---|
| 865 | <ulink url="ch02s04.html">Adding support for other (non-CJKV) languages</ulink>.
|
---|
| 866 | If your language is listed there, Then you have to find javascript version of the
|
---|
| 867 | stemmer. Generally, new stemmers are getting added in to <ulink
|
---|
| 868 | url="http://snowball.tartarus.org/otherlangs/index.html">Snowball Stemmers in
|
---|
| 869 | other languages</ulink> location. If javascript stemmer for your language is
|
---|
| 870 | available, then download it. Else, you can write a new stemmer in JavaScript using
|
---|
| 871 | SnowBall algorithm fairly easily. Algorithms are at <ulink
|
---|
| 872 | url="http://snowball.tartarus.org/">Snowball</ulink>. </para>
|
---|
| 873 | </listitem>
|
---|
| 874 | <listitem>
|
---|
| 875 | <para>Then, name the JS stemmer exactly like this:
|
---|
| 876 | <filename>{$language-code}_stemmer.js</filename>.
|
---|
| 877 | For example, for Italian(it), name it as,
|
---|
| 878 | <filename>it_stemmer.js</filename>. Then, copy it to
|
---|
| 879 | the
|
---|
| 880 | <filename>docbook-webhelp/template/search/stemmers/</filename>
|
---|
| 881 | folder. (I assumed
|
---|
| 882 | <filename>docbook-webhelp</filename> is the root
|
---|
| 883 | folder for webhelp.) <note>
|
---|
| 884 | <para>Make sure you changed the
|
---|
| 885 | <code>webhelp.indexer.language</code> property
|
---|
| 886 | in <filename>build.properties</filename> to your
|
---|
| 887 | language. </para>
|
---|
| 888 | </note>
|
---|
| 889 | </para>
|
---|
| 890 | </listitem>
|
---|
| 891 | <listitem>
|
---|
| 892 | <para>Now two easy changes needed for the indexer.</para>
|
---|
| 893 | <itemizedlist>
|
---|
| 894 | <listitem>
|
---|
| 895 | <para>Open
|
---|
| 896 | <filename>docbook-webhelp/indexer/src/com/nexwave/nquindexer/IndexerTask.java</filename>
|
---|
| 897 | in a text editor and add your language code to the
|
---|
| 898 | <code>supportedLanguages</code> String Array. </para>
|
---|
| 899 | <example>
|
---|
| 900 | <title>Add new language to supportedLanguages array</title>
|
---|
| 901 | <para> change the Array from,
|
---|
| 902 | <programlisting>
|
---|
| 903 | private String[] supportedLanguages= {"en", "de", "fr", "cn", "ja", "ko"};
|
---|
| 904 | //currently extended support available for
|
---|
| 905 | // English, German, French and CJK (Chinese, Japanese, Korean) languages only.
|
---|
| 906 | </programlisting>
|
---|
| 907 | To,</para>
|
---|
| 908 | <programlisting>
|
---|
| 909 | private String[] supportedLanguages= {"en", "de", "fr", "cn", "ja", "ko", <emphasis>"it"</emphasis>};
|
---|
| 910 | //currently extended support available for
|
---|
| 911 | // English, German, French, CJK (Chinese, Japanese, Korean), and Italian languages only.
|
---|
| 912 | </programlisting>
|
---|
| 913 | </example>
|
---|
| 914 | </listitem>
|
---|
| 915 | <listitem>
|
---|
| 916 | <para> Now, open
|
---|
| 917 | <filename>docbook-webhelp/indexer/src/com/nexwave/nquindexer/SaxHTMLIndex.java</filename>
|
---|
| 918 | and add the following line to the code where it initializes the Stemmer (Search
|
---|
| 919 | for <code>SnowballStemmer stemmer;</code>). Then add code to initialize the
|
---|
| 920 | stemmer Object in your language. It's self understandable. See the example. The
|
---|
| 921 | class names are at:
|
---|
| 922 | <filename>docbook-webhelp/indexer/src/com/nexwave/stemmer/snowball/ext/</filename>. </para>
|
---|
| 923 | <example>
|
---|
| 924 | <title>Initialize correct stemmer based on the
|
---|
| 925 | <code>webhelp.indexer.language</code> specified</title>
|
---|
| 926 | <programlisting>
|
---|
| 927 | SnowballStemmer stemmer;
|
---|
| 928 | if(indexerLanguage.equalsIgnoreCase("en")){
|
---|
| 929 | stemmer = new EnglishStemmer();
|
---|
| 930 | } else if (indexerLanguage.equalsIgnoreCase("de")){
|
---|
| 931 | stemmer= new GermanStemmer();
|
---|
| 932 | } else if (indexerLanguage.equalsIgnoreCase("fr")){
|
---|
| 933 | stemmer= new FrenchStemmer();
|
---|
| 934 | }
|
---|
| 935 | <emphasis>else if (indexerLanguage.equalsIgnoreCase("it")){ //If language code is "it" (Italian)
|
---|
| 936 | stemmer= new italianStemmer(); //Initialize the stemmer to <code>italianStemmer</code> object.
|
---|
| 937 | } </emphasis>
|
---|
| 938 | else {
|
---|
| 939 | stemmer = null;
|
---|
| 940 | }
|
---|
| 941 | </programlisting>
|
---|
| 942 | </example>
|
---|
| 943 | </listitem>
|
---|
| 944 | </itemizedlist>
|
---|
| 945 | </listitem>
|
---|
| 946 | </itemizedlist>
|
---|
| 947 | </para>
|
---|
| 948 | <para>That's all. Now run <code>ant build-indexer</code> to compile and build the java code.
|
---|
| 949 | Then, run <code>ant webhelp</code> to generate the output from your docbook file. For any
|
---|
| 950 | questions, contact us or email to the docbook mailing list
|
---|
| 951 | <email>docbook-apps@lists.oasis-open.org</email>.</para>
|
---|
| 952 | <indexterm>
|
---|
| 953 | <primary>stemmer</primary>
|
---|
| 954 | </indexterm>
|
---|
| 955 | </section>
|
---|
| 956 | </section>
|
---|
| 957 | </chapter>
|
---|
| 958 | <chapter>
|
---|
| 959 | <chapterinfo>
|
---|
| 960 | <abstract>
|
---|
| 961 | <para>Frequently Asked Questions</para>
|
---|
| 962 | </abstract>
|
---|
| 963 | </chapterinfo>
|
---|
| 964 | <title>FAQ</title>
|
---|
| 965 | <qandaset>
|
---|
| 966 | <qandaentry>
|
---|
| 967 | <question>
|
---|
| 968 | <para>On what browsers and operating systems WebHelp has tested extensively?</para>
|
---|
| 969 | </question>
|
---|
| 970 | <answer>
|
---|
| 971 | <para>We tested it with versions of most browsers including Firefox 3.x+, IE 7+, Chrome,
|
---|
| 972 | Safari, and iPod/iPhone. The JavaScript codes are mostly jquery plugins, so you’d want
|
---|
| 973 | to check the jquery support matrix for details.</para>
|
---|
| 974 | </answer>
|
---|
| 975 | </qandaentry>
|
---|
| 976 | <qandaentry>
|
---|
| 977 | <question>
|
---|
| 978 | <para>Apart from this demo, where can I find other demos or production deployments of
|
---|
| 979 | WebHelp?</para>
|
---|
| 980 | </question>
|
---|
| 981 | <answer>
|
---|
| 982 | <para>There are four production deployments provided in <ulink
|
---|
| 983 | url="http://wiki.docbook.org/WebHelp">WebHelp wiki</ulink> currently.</para>
|
---|
| 984 | </answer>
|
---|
| 985 | </qandaentry>
|
---|
| 986 | <qandaentry>
|
---|
| 987 | <question>
|
---|
| 988 | <para>When building the webhelp output, I'm getting the following error. What's the reason
|
---|
| 989 | for this?</para>
|
---|
| 990 | <programlisting>[xslt] : Warning! file:/C:/Users/kasun/docbook-xsl-1.77.0/xhtml/autoidx.xsl:
|
---|
| 991 | line 596: Attribute 'href' outside of element.
|
---|
| 992 | [xslt] : Warning! file:/C:/Users/kasun/docbook-xsl-1.77.0/xhtml/autoidx.xsl:
|
---|
| 993 | line 596: Attribute 'href' outside of element.</programlisting>
|
---|
| 994 | <para>----</para>
|
---|
| 995 | </question>
|
---|
| 996 | <answer>
|
---|
| 997 | <para>This happens if you haven't done the step 3 and 4 of webhelp build guide "Generating
|
---|
| 998 | webhelp output" in the documentation. Basically, you need to correctly set the following
|
---|
| 999 | folder
|
---|
| 1000 | paths.<programlisting>xslt-processor-classpath=/usr/share/java/saxon-6.5.5.jar
|
---|
| 1001 | xercesImpl.jar=/usr/share/java/xercesImpl.jar
|
---|
| 1002 | xml-apis.jar=/usr/share/java/xml-apis.jar</programlisting></para>
|
---|
| 1003 | </answer>
|
---|
| 1004 | </qandaentry>
|
---|
| 1005 | <qandaentry>
|
---|
| 1006 | <question>
|
---|
| 1007 | <para>Does WebHelp Indexer can index HTML transformation as well?</para>
|
---|
| 1008 | </question>
|
---|
| 1009 | <answer>
|
---|
| 1010 | <para>Yes, WebHelp supports HTML transformations as well in addition to XHTML.</para>
|
---|
| 1011 | </answer>
|
---|
| 1012 | </qandaentry>
|
---|
| 1013 | <qandaentry>
|
---|
| 1014 | <question>
|
---|
| 1015 | <para>I need more information about webhelp-indexer. Where can I find it?</para>
|
---|
| 1016 | </question>
|
---|
| 1017 | <answer>
|
---|
| 1018 | <para>The DocBook Webhelp Indexer is based on the HTMLSearch plugin for DITA. See <ulink
|
---|
| 1019 | url="http://www.helpml.com:8088/help/index.jsp?topic=/org.sample.help.doc/htmlsearch/DHSC_BestPractices_htmlsearch.html"
|
---|
| 1020 | >HTMLSearch documentation </ulink> for more information.</para>
|
---|
| 1021 | </answer>
|
---|
| 1022 | </qandaentry>
|
---|
| 1023 | </qandaset>
|
---|
| 1024 | <indexterm>
|
---|
| 1025 | <primary>FAQ</primary>
|
---|
| 1026 | </indexterm>
|
---|
| 1027 | </chapter>
|
---|
| 1028 | <xi:include href="xinclude-test.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
|
---|
| 1029 | <index/>
|
---|
| 1030 | </book>
|
---|