</itemizedlist>
<itemizedlist>
<title>Limitations and annoyances</title>
+ <listitem>
+ <para>You must use xhtml output because the search indexer cannot index html.</para>
+ </listitem>
<listitem>
<para>No support for stemming. If you search for "start" it will not find "started" and vice versa.</para>
</listitem>
<listitem>
<para>A customization to the xsls is included to put any <sgmltag>indexterm</sgmltag>s in the <sgmltag class="emptytag">meta name="keywords"...</sgmltag> element. The main reason for doing this is to improve support for Asian languages and help compensate for the lack of stemming in the indexer. As implmented, this customization only supports situations where all sections or sect* elements are chunked. For example, if you have chunk.first.sections set to 0, any indexterms in the first sections will not be appended to the keywords list. </para>
</listitem>
+ <listitem>
+ <para>By design, the indexer does not index <filename>index.html</filename> or <filename>ix01.html</filename>. Unfortunately, this is currently hard coded in the indexer. </para>
+ </listitem>
</itemizedlist>
<itemizedlist>
<title>Enhancements planned as part of GSOC 2010</title>
<listitem>
<para>Move the header Next and Prev links to the banner</para>
</listitem>
+ <listitem>
+ <para>Parameterize width of the TOC pane OR make the TOC pane resizable by the user.</para>
+ </listitem>
</itemizedlist>
<itemizedlist>
<title>Future enhancements</title>
+ <listitem>
+ <para>Add "Expand all" and "Collapse all" buttons to the toc. </para>
+ </listitem>
<listitem>
<para>Add an option to use Lucene for server-side searches with toc state persisted on the server.</para>
</listitem>
+ <listitem>
+ <para>Sort search results based on relevance</para>
+ </listitem>
<listitem>
- <para>Automatically limit the size of the search description to something 140 characters.</para>
+ <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>
+ <listitem>
+ <para>Automatically limit the size of the search description to something 140 characters.</para>
+ </listitem>
+ </itemizedlist>
</listitem>
<listitem>
<para>Support boolean operators in search.</para>
<title>Installation</title>
<procedure>
<title>To install the package</title>
+ <step>
+ <para>If necessary, install <ulink url="http://www.java.com/en/download/manual.jsp">Java 1.5</ulink> or higher. </para>
+ <substeps>
+ <step>
+ <para>Confirm that Java is installed and in your <envar>PATH</envar> by typing: <programlisting>java -version</programlisting></para>
+ </step>
+ </substeps>
+ </step>
<step>
- <para>Confirm that you have Java 1.5 or higher and Ant 1.6.5 or higher installed.</para>
+ <para>If necessary, install <ulink url="http://ant.apache.org/bindownload.cgi">Apache Ant 1.6.5</ulink> or higher installed.</para>
+ <substeps>
+ <step>
+ <para>Unzip the Ant binary distribution to a convenient location on your system. For example: <filename>c:\Program Files</filename>.</para>
+ </step>
+ <step>
+ <para>Set the environment variable <envar>ANT_HOME</envar> to the top-level Ant directory. For example: <filename>c:\Program Files\apache-ant-1.7.1</filename>.</para>
+ </step>
+ <step>
+ <para>Add the Ant <filename>bin</filename> directory to your <envar>PATH</envar>. For example: <filename>c:\Program Files\apache-ant-1.7.1\bin</filename></para>
+ </step>
+ </substeps>
</step>
<step>
- <para>Confirm that you have <ulink url="http://xml.apache.org/commons/dist">xml-commons-resolver.jar</ulink> in your CLASSPATH.</para>
+ <para>If necessary, download <ulink url="http://xml.apache.org/commons/dist">xml-commons-resolver.jar</ulink> and add it to your <envar>CLASSPATH</envar>.</para>
</step>
<step>
- <para>Download the package <!--ulink url="http://www.thingbag.net/docbook/docbook-webhelp.zip">docbook-webhelp.zip</ulink--> and unzip it somewhere convenient.</para>
+ <para>Obtain the package. <!--ulink url="http://www.thingbag.net/docbook/docbook-webhelp.zip">docbook-webhelp.zip</ulink--> Currently, the webhelp package is only available through Subversion.</para>
+ <substeps>
+ <step>
+ <para>If necessary, install a <ulink url="http://en.wikipedia.org/wiki/Comparison_of_Subversion_clients">Subversion client</ulink>.</para>
+ </step>
+ <step>
+ <para>In a convenient location on your system, run the command <programlisting>svn co https://docbook.svn.sourceforge.net/svnroot/docbook/branches/webhelp/xsl/webhelp webhelp</programlisting></para>
+ </step>
+ </substeps>
</step>
+ <step>
+ <para>To improve performance, download and extract DocBook XSLs to a convenient location on your file system. Currently, this package supports <ulink url="http://sourceforge.net/projects/docbook/files/#files">docbook-xsl</ulink> (i.e. it does not yet support the namespace version of the xsls and does not yet strip the namespace from DocBook 5.x documents. </para>
+ </step>
+ <step>
+ <para>In a text editor, edit the <filename>build.properties</filename> file in the webhelp directory and make the changes indicated by the comments:<programlisting>input-xml=docsrc/readme.xml
+frameset.base.dir=doc
+
+# Modify this so that it points to your copy of the Saxon 6.5 jar.
+xslt-processor-classpath=c:/workhead/export/saxon/6.5/lib/saxon.jar
+
+# To use this catalog, make sure the resolver is in your classpath.
+# Download xml-commons-resolver from http://xml.apache.org/commons/dist/
+# and add it to your CLASSPATH. Then use the following property to point
+# to your docbook xsl stylesheets' catalog. If you omit this step,
+# the xsls will use the stylesheets off the internet, which
+# will slow down your document generation.
+docbook-xsl-catalog=c:/gsoc2010/docbook-xsl-1.75.2/catalog.xml
+
+# If you wish to have the ant script validate the document before
+# building it, set this property to the location
+# of your DocBook DTD. The sample document is
+# a DocBook 4.5 document and uncomment the line validate=true.
+docbookx.dtd=c:/workhead/export/DocBookDTD/4.5/docbookx.dtd
+#validate=true</programlisting></para>
+ </step>
<step>
- <para>Test the package by running <code>ant webhelp</code>. It should generate a copy of this documentation in the <filename class="directory">doc</filename> directory.</para>
+ <para>Test the package by running the command <code>ant webhelp</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.</para>
</step>
<step>
<para>If you wish to use the included <filename>build.xml</filename> file for your own content, create a <filename>build.xml</filename> file that imports the one from this package:
<para>Add some code to the main ant script to copy your images to the output directory.</para>
</step>
</procedure>
- <note>
- <para>By design, the indexer does not index <filename>index.html</filename> or <filename>ix01.html</filename>. Unfortunately, this is currently hard coded in the indexer. </para>
- </note>
</section>
<section>
<title>Using the output</title>
projects / docbook-dsssl / commitdiff