diff options
Diffstat (limited to 'webhelp/docsrc/readme.xml')
| -rw-r--r-- | webhelp/docsrc/readme.xml | 263 |
1 files changed, 134 insertions, 129 deletions
diff --git a/webhelp/docsrc/readme.xml b/webhelp/docsrc/readme.xml index e45ee24..ea48969 100644 --- a/webhelp/docsrc/readme.xml +++ b/webhelp/docsrc/readme.xml @@ -52,8 +52,13 @@ 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 @@ -65,12 +70,16 @@ </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> @@ -96,6 +105,12 @@ 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" >OpenStack</ulink>.</para> @@ -196,86 +211,53 @@ <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> + <title>To install the package</title> <note> - <para>The examples in this procedure assume a Windows installation, but the process is the - same in other environments, <foreignphrase>mutatis mutandis</foreignphrase>.</para> - <para>In addition to using the ant - <filename>build.xml</filename> provided, you can also - use the <ulink url="http://docbkx-tools.sourceforge.net/docbkx-samples/manual.html">Docbkx Maven plugin</ulink> to generate - webhelp.</para> + <para>The examples in this procedure assume a Windows + installation, but the process is the same in other + environments, <foreignphrase>mutatis + mutandis</foreignphrase>. 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>. You can also use + the <ulink + url="http://docbkx-tools.sourceforge.net/docbkx-samples/manual.html" + >Docbkx Maven plugin</ulink> to generate webhelp.</para> </note> <step> <para>If necessary, install <ulink url="http://www.java.com/en/download/manual.jsp">Java @@ -332,14 +314,15 @@ <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> + <para>Download <ulink + url="https://xerces.apache.org/xerces2-j/">Xerces2 + Java</ulink> and extract it to a convenient location on + your file system. You will need the + <filename>xercesImpl.jar</filename> and + <filename>xml-apis.jar</filename> from this distribution + in in <xref linkend="edit-build-properties"/>. </para> + </step> <step id="edit-build-properties"> <para>In a text editor, edit the <filename>build.properties</filename> file in the @@ -382,7 +365,7 @@ stylesheet-path=${ant.file.dir}/xsl/webhelp.xsl # 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 @@ -390,7 +373,7 @@ stylesheet-path=${ant.file.dir}/xsl/webhelp.xsl 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 @@ -417,16 +400,15 @@ admon.graphics=0 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 @@ -496,10 +478,10 @@ suppress.footer.navigation=0</programlisting></para> </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"/> @@ -533,19 +515,25 @@ suppress.footer.navigation=0</programlisting></para> </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> @@ -796,19 +784,26 @@ persist: "cookie" 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 @@ -817,11 +812,14 @@ persist: "cookie" 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> @@ -875,12 +873,18 @@ persist: "cookie" </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> @@ -1021,5 +1025,6 @@ xml-apis.jar=/usr/share/java/xml-apis.jar</programlisting></para> <primary>FAQ</primary> </indexterm> </chapter> - <!--<xi:include href="xinclude-test.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>--> + <xi:include href="xinclude-test.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <index/> </book> |