source: stylesheets/lfs-xsl/docbook-xsl-1.78.1/webhelp/docsrc/readme.xml@ f6e9c180

7.6-systemd 7.7-systemd 7.8-systemd 7.9-systemd
Last change on this file since f6e9c180 was b1a51ac1, checked in by Krejzi <krejzi@…>, 11 years ago

Import new branch

git-svn-id: ​http://svn.linuxfromscratch.org/LFS/branches/systemd/BOOK@10389 4aa44e1e-78dd-0310-a6d2-fbcd4c07a689
  • Property mode set to 100644
File size: 49.5 KB
Line 
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.
346input-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.
350output-dir=docs
351
352# If you are using a customization layer that imports webhelp.xsl, use
353# this property to point to it.
354stylesheet-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
373xslt-processor-classpath=/usr/share/java/saxon-6.5.5.jar
374xercesImpl.jar=/usr/share/java/xercesImpl.jar
375xml-apis.jar=/usr/share/java/xml-apis.jar
376</emphasis>
377# For non-ns version only, this validates the document
378# against a dtd.
379validate-against-dtd=true
380
381# The extension for files to be indexed (html/htm/xhtml etc.)
382html.extension=html
383
384# Set this to false if you don't need a search tab.
385webhelp.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.
392webhelp.indexer.language=en
393
394# Enables/Disables stemming
395# Stemming allows better querying for the search
396enable.stemming=true
397
398# Set admon.graphics to 1 to user graphics for note, tip, etc.
399admon.graphics=0
400suppress.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>&lt;project&gt;
422 &lt;property name="input-xml" value="<replaceable>path-to/yourfile.xml</replaceable>"/&gt;
423 &lt;property name="input-images-dirs" value="<replaceable>images/** figures/** graphics/**</replaceable>"/&gt;
424 &lt;property name="output-dir" value="<replaceable>path-to/desired-output-dir</replaceable>"/&gt;
425 &lt;import file="<replaceable>path-to/docbook-webhelp/</replaceable>build.xml"/&gt;
426&lt;/project&gt;</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 &lt;FilesMatch "\.(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$"&gt; # <co id="CachingSettings"/>
488 Header set Cache-Control "max-age=290304000, public"
489 &lt;/FilesMatch&gt;
490
491 # 2 DAYS
492 &lt;FilesMatch "\.(xml|txt)$"&gt;
493 Header set Cache-Control "max-age=172800, public, must-revalidate"
494 &lt;/FilesMatch&gt;
495
496 # 2 HOURS
497 &lt;FilesMatch "\.(html|htm)$"&gt;
498 Header set Cache-Control "max-age=7200, must-revalidate"
499 &lt;/FilesMatch&gt;
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 &lt;Files *.html&gt;
514 SetOutputFilter DEFLATE
515 &lt;/Files&gt;
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>&lt;figure>
695 &lt;title>Sample&lt;/title>
696 &lt;mediaobject>
697 &lt;imageobject>
698 &lt;imagedata fileref="<emphasis role="bold">images/sample.jpg</emphasis>" format="JPG"/>
699 &lt;/imageobject>
700 &lt;/mediaobject>
701&lt;/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.
711input-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>&lt;ul> &lt;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({
760collapsed: true,
761animated: "medium",
762control: "#sidetreecontrol",
763persist: "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>
903private 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>
909private 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
1001xercesImpl.jar=/usr/share/java/xercesImpl.jar
1002xml-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>
Note: See TracBrowser for help on using the repository browser.