ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</para>
</formalpara>
- <para>This package is maintained by Kasun Gajasinghe, <email>kasunbg AT gmail DOT com</email>
- and David Cramer, <email>david AT thingbag DOT net</email>.</para>
+ <para>This package is maintained by Kasun Gajasinghe,
+ <email>kasunbg AT gmail DOT com</email> and David Cramer,
+ <email>david AT thingbag DOT net</email> and with
+ contributions by Arun Bharadwaj and Visitha Baddegama. Please
+ direct support questions to the <ulink
+ url="http://wiki.docbook.org/DocBookDiscussion">DocBook-apps
+ mailing list</ulink>. </para>
<para>This package also includes the following software written and copyrighted by others:<itemizedlist>
<listitem>
<para>Files in <filename class="directory">template/common/jquery</filename> are
</indexterm>
</listitem>
<listitem>
- <para>Some files in the <filename class="directory">template/content/search</filename>
- and <filename class="directory">indexer</filename> directories were originally part of
- N. Quaine's htmlsearch DITA plugin. The htmlsearch DITA plugin is available from the
- <ulink url="http://tech.groups.yahoo.com/group/dita-users/files/Demos/">files
- page</ulink> of the DITA-users yahoogroup. The htmlsearch plugin was released under
- a BSD-style license. See <filename>indexer/license.txt</filename> for details. <indexterm>
+ <para>Some files in the <filename class="directory"
+ >template/search</filename> and <filename
+ class="directory">indexer</filename> directories were
+ originally part of N. Quaine's htmlsearch DITA plugin.
+ The htmlsearch DITA plugin is available from the <ulink
+ url="http://tech.groups.yahoo.com/group/dita-users/files/Demos/"
+ >files page</ulink> of the DITA-users yahoogroup. The
+ htmlsearch plugin was released under a BSD-style
+ license. See <filename>indexer/license.txt</filename>
+ for details. <indexterm>
<primary>htmlsearch</primary>
</indexterm>
<indexterm>
Ltd.</ulink>, the publishers of the oXygen XML
Editor.</para>
</listitem>
+ <listitem>
+ <para><ulink url="http://ccil.org/~cowan/XML/tagsoup/"
+ >TagSoup</ulink>, released under the Apache 2.0
+ license, makes it possible to index html instead of just
+ xhtml output. </para>
+ </listitem>
<listitem>
<para>Cosmetic improvements provided by <ulink
url="http://docs.openstack.org"
<para>TOC and search pane implemented without the use of a frameset.</para>
</listitem>
<listitem>
- <para>An Ant script to generate output. You can use this
- build file by importing it into your own or use it as a
- model for integrating this output format into your own
- build system. Alternatively, you can use this Ant script
- as a template for creating your own build script or you
- can use the <ulink
+ <para>An Ant script and sample Makefile to generate output.
+ You can use the ant build file by importing it into your
+ own or use it as a model for integrating this output
+ format into your own build system. Alternatively, you can
+ use the build scripts as a template for creating your own
+ script. You can also generate webhelp from DocBook using
+ the <ulink
url="http://docbkx-tools.sourceforge.net/docbkx-samples/manual.html"
>Docbkx Maven plugin</ulink>.</para>
</listitem>
</itemizedlist></para>
-<!-- <para>Following are possible enhancements that can be applied to webhelp. You are welcome to
- send us new suggestions, code contributions etc.<itemizedlist>
- <title>Possible future enhancements</title>
- <listitem>
- <para>Adjust css so that there is a visual indication that you have move the focus from the contents to the search tab using the tab key.</para>
- </listitem>
- <listitem>
- <para>Add "Expand all" and "Collapse all" buttons to the table of contents.</para>
- </listitem>
- <listitem>
- <para>Parameterize width of the TOC pane OR make the TOC pane resizeable by the
- user.</para>
- </listitem>
- <listitem>
- <para>Automate search results summary text:</para>
- <itemizedlist>
- <listitem>
- <para>Automatically use the first non-heading content as the summary in the search
- results.</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>Support boolean operators in search.</para>
- </listitem>
- <listitem>
- <para>Add an index tab populated by a separate JavaScript file. Include a param/property
- that allows the content creator to disable the index.</para>
- </listitem>
- <listitem>
- <para>Add functionality to the <filename>build.xml</filename> file so that when a property
- is set, the build generates a pdf version of the document and includes a link to it from
- the header.</para>
- </listitem>
- <listitem>
- <para>Add <ulink
- url="http://www.comparenetworks.com/developers/jqueryplugins/jbreadcrumb.html"
- >breadcrumbs</ulink> so the user will know what topics he's been to.</para>
- </listitem>
- <listitem>
- <para>Consider using more advanced Lucene indexers for Chinese and Japanese than the
- CJKAnalyzer</para>
- </listitem>
- <listitem>
- <para>And, a lot more (with duplicates) at <ulink
- url="http://docbook.xmlpress.net/tiki-index.php?page=WebHelpIdeas">WebHelp Ideas Wiki at
- XMLPress </ulink></para>
- </listitem>
- </itemizedlist></para>-->
</chapter>
<chapter>
<title>Using the package</title>
<para role="summary">The following sections describe how to
- install and use the package on Windows. </para>
+ install and use the package on Windows with the sample Ant build
+ script. In an environment where unix shell command are
+ available, you can also use the
+ <filename>Makefile.sample</filename> as a starting point for
+ creating your build script. To use
+ <filename>Makefile.sample</filename> you must have
+ <command>xsltproc</command> and <command>java</command>
+ available in your <envar>PATH</envar>.</para>
<section>
<sectioninfo>
<abstract>
<para>Installation instructions</para>
</abstract>
</sectioninfo>
- <title>Generating webhelp output</title>
+ <title>Generating webhelp output using the Ant build.xml
+ file</title>
<procedure>
<title>To install the package on Windows</title>
<note>
<envar>CLASSPATH</envar>.</para>
</note></para>
</step>
-<!-- <step>
- <para>If you are using Ant 1.8.1 or higher, you may need to add
- <filename>xercesImpl.jar</filename>, and <filename>xml-apis.jar</filename> to the
- classpath. See <function>index</function> target in the Ant script to see how it's
- currently added. <note>
- <para>The way webhelp indexer is invoked is made easier after the XSL-1.76.1 release. </para>
- </note></para>
- </step>-->
<step id="edit-build-properties">
<para>In a text editor, edit the
<filename>build.properties</filename> file in the
# and uncomment this line.
#input-images-basedir=/path/to/image/location
-# Modify the follosing so that they point to your local
+<emphasis># Modify the follosing so that they point to your local
# copy of the jars indicated:
# * Saxon 6.5 jar
# * Xerces 2: xercesImpl.jar
xslt-processor-classpath=/usr/share/java/saxon-6.5.5.jar
xercesImpl.jar=/usr/share/java/xercesImpl.jar
xml-apis.jar=/usr/share/java/xml-apis.jar
-
+</emphasis>
# For non-ns version only, this validates the document
# against a dtd.
validate-against-dtd=true
suppress.footer.navigation=0</programlisting></para>
</step>
<step>
- <para>Test the package by running the command <code>ant webhelp
- -Doutput-dir=test-ouput</code> at the command line in the webhelp directory. It should
- generate a copy of this documentation in the <filename class="directory">doc</filename>
- directory. Type <code>start test-output\index.html</code> to open the output in a
- browser. Once you have confirmed that the process worked, you can delete the <filename
- class="directory">test-output</filename> directory. <important>
- <para>The Saxon 6.5 jar should <emphasis>not</emphasis> be in your
- <envar>CLASSPATH</envar> when you generate the webhelp output. If you have any
- problems, try running ant with an empty <envar>CLASSPATH</envar>.</para>
- </important></para>
+ <para>Test the package by running the command <code>ant
+ webhelp -Doutput-dir=test-ouput</code> at the command
+ line in the webhelp directory. It should generate a copy
+ of this documentation in the <filename class="directory"
+ >doc</filename> directory. Type <code>start
+ test-output\index.html</code> to open the output in a
+ browser. Once you have confirmed that the process worked,
+ you can delete the <filename class="directory"
+ >test-output</filename> directory. </para>
</step>
<step>
<para>To process your own document, simply refer to this package from another
</itemizedlist></para>
<section>
<title>Recommended Apache configurations</title>
- <para>If you are serving a long document from an Apache web server, we recommend you make
- the following additions or changes to your <filename>httpd.conf</filename> or
- <filename>.htaccess</filename> file. <remark>TODO: Explain what each thing
-
does.</remark><programlisting>AddDefaultCharSet UTF-8 # <co id="AddDefaultCharSet"/>
+ <para>If you are serving a long document from an Apache web
+ server, we recommend you make the following additions or
+ changes to your <filename>httpd.conf</filename> or
+
<filename>.htaccess</filename> file. <programlisting>AddDefaultCharSet UTF-8 # <co id="AddDefaultCharSet"/>
# 480 weeks
<FilesMatch "\.(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$"> # <co id="CachingSettings"/>
</Files>
</programlisting><calloutlist>
<callout arearefs="AddDefaultCharSet">
- <para>See <ulink url="http://www.sagehill.net/docbookxsl/SpecialChars.html">Odd
- characters in HTML output</ulink> in Bob Stayton's book <citetitle>DocBook XSL:
- The Complete Guide</citetitle> for more information about this setting.</para>
+ <para>See <ulink
+ url="http://www.sagehill.net/docbookxsl/SpecialChars.html"
+ >Odd characters in HTML output</ulink> in Bob
+ Stayton's book <citetitle>DocBook XSL: The Complete
+ Guide</citetitle> for more information about this
+ setting.</para>
</callout>
<callout arearefs="CachingSettings">
- <para>These lines and those that follow cause the browser to cache various resources
- such as bitmaps and JavaScript files. Note that caching JavaScript files could cause
- your users to have stale search indexes if you update your document since the search
- index is stored in JavaScript files.</para>
+ <para>These lines and those that follow cause the
+ browser to cache various resources such as bitmaps and
+ JavaScript files. Note that caching JavaScript files
+ could cause your users to have stale search indexes if
+ you update your document since the search index is
+ stored in JavaScript files.</para>
</callout>
<callout arearefs="CompressSetting">
- <para>These lines cause the the server to compress html, css, and JavaScript files and
- the brower to uncompress them to improve download performance.</para>
+ <para>These lines cause the the server to compress html,
+ css, and JavaScript files and the brower to uncompress
+ them to improve download performance.</para>
</callout>
</calloutlist></para>
</section>
a simplified 'index' that too resides in JavaScript. Mainly the search mechanism has two
parts. <itemizedlist>
<listitem>
- <para>Indexing: First we need to traverse the content in the docs/content folder and
- index the words in it. This is done by <filename>webhelpindexer.jar</filename> in
- <filename>xsl/extentions/</filename> folder. You can invoke it by <code>ant
- index</code> command from the root of webhelp of directory. The source of
+ <para>Indexing: First we need to traverse the content in
+ the docs folder and index the words in it. This is done
+ by <filename>webhelpindexer.jar</filename> in
+ <filename>xsl/extentions/</filename> folder. You can
+ invoke it by <code>ant index</code> command from the
+ root of webhelp of directory. The source of
webhelpindexer is now moved to it's own location at
- <filename>trunk/xsl-webhelpindexer/</filename>. Checkout the Docbook trunk svn
- directory to get this source. Then, do your changes and recompile it by simply running
- <code>ant</code> command. My assumption is that it can be opened by Netbeans IDE by
- one click. Or if you are using IntelliJ Idea, you can simply create a new project from
- existing sources. Indexer has extensive support for features such as word scoring,
- stemming of words, and support for languages English, German, French. For CJK
- (Chinese, Japanese, Korean) languages, it uses bi-gram tokenizing to break up the
- words (since CJK languages does not have spaces between words).</para>
+ <filename>trunk/xsl-webhelpindexer/</filename>.
+ Checkout the Docbook trunk svn directory to get this
+ source. Then, do your changes and recompile it by simply
+ running <code>ant</code> command. My assumption is that
+ it can be opened by Netbeans IDE by one click. Or if you
+ are using IntelliJ Idea, you can simply create a new
+ project from existing sources. Indexer has extensive
+ support for features such as word scoring, stemming of
+ words, and support for languages English, German,
+ French. For CJK (Chinese, Japanese, Korean) languages,
+ it uses bi-gram tokenizing to break up the words (since
+ CJK languages does not have spaces between
+ words).</para>
<para> When <code>ant index</code> is run, it generates five output files: <itemizedlist>
<listitem>
<para><filename>htmlFileList.js</filename> - This contains an array named
to false.</para>
</listitem>
<listitem>
- <para><filename>htmlFileInfoList.js</filename> - This includes some meta data
- about the indexed files in an array named <code>fil</code>. It includes details
- about file name, file (html) title, a summary of the content.Format would look
- like, <code>fil["4"]= "ch03.html@@@Developer Docs@@@This chapter provides an
- overview of how webhelp is implemented.";</code>
+ <para><filename>htmlFileInfoList.js</filename> -
+ This includes some meta data about the indexed
+ files in an array named <code>fil</code>. It
+ includes details about file name, file (html)
+ title, a summary of the content. Format would look
+ like, <code>fil["4"]= "ch03.html@@@Developer
+ Docs@@@This chapter provides an overview of how
+ webhelp is implemented.";</code>
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>Then, name the JS stemmer exactly like this:
- <filename>{$language-code}_stemmer.js</filename>. For example, for Italian(it),
- name it as, <filename>it_stemmer.js</filename>. Then, copy it to the
- <filename>docbook-webhelp/template/content/search/stemmers/</filename> folder. (I
- assumed <filename>docbook-webhelp</filename> is the root folder for webhelp.) <note>
- <para>Make sure you changed the <code>webhelp.indexer.language</code> property in
- <filename>build.properties</filename> to your language. </para>
+ <filename>{$language-code}_stemmer.js</filename>.
+ For example, for Italian(it), name it as,
+ <filename>it_stemmer.js</filename>. Then, copy it to
+ the
+ <filename>docbook-webhelp/template/search/stemmers/</filename>
+ folder. (I assumed
+ <filename>docbook-webhelp</filename> is the root
+ folder for webhelp.) <note>
+ <para>Make sure you changed the
+ <code>webhelp.indexer.language</code> property
+ in <filename>build.properties</filename> to your
+ language. </para>
</note>
</para>
</listitem>
projects / docbook-dsssl / commitdiff