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