X-Git-Url: https://git.stg.codes/stg.git/blobdiff_plain/793149f04ce52bf75dc4efb7b83a3f8ed30d1fff..35ec793690104efdd610964d255302a0310a2daf:/doc/xslt/webhelp/docsrc/readme.xml diff --git a/doc/xslt/webhelp/docsrc/readme.xml b/doc/xslt/webhelp/docsrc/readme.xml deleted file mode 100755 index 4d191906..00000000 --- a/doc/xslt/webhelp/docsrc/readme.xml +++ /dev/null @@ -1,928 +0,0 @@ - - - - README: Web-based Help from DocBook XML - - - - Permission is hereby granted, free of charge, to any person - obtaining a copy of this software and associated documentation files - (the Software), to deal in the Software without - restriction, including without limitation the rights to use, copy, - modify, merge, publish, distribute, sublicense, and/or sell copies of - the Software, and to permit persons to whom the Software is furnished to - do so, subject to the following conditions: - - The above copyright notice and this permission notice shall - be included in all copies or substantial portions of the - Software. - - - - Except as contained in this notice, the names of individuals - credited with contribution to this software shall not be used in - advertising or otherwise to promote the sale, use or other - dealings in this Software without prior written authorization from - the individuals in question. - - - - Any stylesheet derived from this Software that is publicly - distributed will be identified with a different name and the - version strings in any derived Software will be changed so that no - possibility of confusion between the derived package and this - Software will exist. - - - - - Warranty: - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. - IN NO EVENT SHALL DAVID CRAMER, KASUN GAJASINGHE, OR ANY OTHER CONTRIBUTOR BE LIABLE FOR - ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 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. - - - This package is maintained by Kasun Gajasinghe, kasunbg AT - gmail DOT com and David Cramer, david AT thingbag DOT - net. - - This package also includes the following software written and - copyrighted by others: - - Files in template/common/jquery are - copyrighted by JQuery - under the MIT License. The file - jquery.cookie.js Copyright (c) 2006 Klaus - Hartl under the MIT license. - - - jquery - - - - - Some files in the template/content/search and indexer directories were originally - part of N. Quaine's htmlsearch DITA plugin. The htmlsearch DITA - plugin is available from the files - page of the DITA-users yahoogroup. The htmlsearch plugin - was released under a BSD-style license. See - indexer/license.txt for details. - htmlsearch - - DITA - - htmlsearch plugin - - - - - Stemmers from the Snowball - project released under a BSD license. - - - - Code from the Apache - Lucene search engine provides support for tokenizing - Chinese, Japanese, and Korean content released under the Apache - 2.0 license. - - - Webhelp for DocBook was developed as a Google Summer of Code project. - - - - - 2008-2010 - - Kasun Gajasinghe - - David Cramer - - - - David - - Cramer - - dcramer AT motive DOT com - - david AT thingbag DOT net - - - - Kasun - - Gajasinghe - - kasunbg AT gmail DOT com - - - August 2010 - - - - - - - - Overview of the package. - - - - Introduction - - A common requirement for technical publications groups is to produce a Web-based help - format that includes a table of contents pane, a search feature, and an index similar to what - you get from the Microsoft HTML Help (.chm) format or Eclipse help. If the content is help for - a Web application that is not exposed to the Internet or requires that the user be logged in, - then it is impossible to use services like Google to add search. - features - - - Features - - Full text search. - search - features - - - - Stemming support for English, French, and German. Stemming support can be added - for other languages by implementing a stemmer. - search - stemming - - - - Support for Chinese, Japanese, and Korean using code from the Lucene search - engine. - - - Search highlighting shows where the searched for term appears in the results. - Use the H button to toggle the highlighting off and on. - - search - highlighting - - - - Search results can include brief descriptions of the target. - search - descriptions - - - - - - Table of contents pane with collapsible toc tree. - - - Auto-synchronization of content pane and TOC. - - - TOC and search pane implemented without the use of a frameset. - - - An Ant build.xml file 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. - - - - Possible future enhancements - - Move webhelp-specific parameters and gentext strings into base DocBook stylesheets. - - - - Use tabindex attributes to control the tab - order in the output. The Contents and Search tabs should be first and second, then the - search box and button, then the table of contents items, and so on. - - - Add "Expand all" and "Collapse all" buttons to the table of contents. - - - Add other search options: - - - Add an option to use Lucene for server-side searches with table of contents - state persisted on the server. - - - Add a simple form that uses a Google site:my.domain.com based search. - - - - - Sort search results based on relevance - - - Support wild card characters in the search query. - - - Parameterize width of the TOC pane OR make the TOC pane resizeable by the - user. - - - Automate search results summary text: - - - Automatically use the first non-heading content as the summary in the search - results. - - - Automatically limit the size of the search description to something 140 - characters. - - - - - Support boolean operators in search. - - - Parameterize list of files to exclude from indexing. Currently it's hard coded that - we don't index index.html and ix01.html (the - legal notice and index topics). It should be smarter and automatically not index the - index file even if it's not named ix01.html. - - - Improve performance by moving the table of contents div out of each page and into a - separate JavaScript file which then adds it to the page. - - - Add to the indexer the ability to specify a list of files or file patterns not to - index. Currently it does not index index.html or - ix01.html, which is generally appropriate, but it should be up to - the user to decide. - - - Add an index tab populated by a separate JavaScript file. Include a param/property - that allows the content creator to disable the index. - - - Add functionality to the build.xml 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. - - - Add breadcrumbs so the user will know what topics he's been to. - - - Consider using more advanced Lucene indexers for Chinese and Japanese than the - CJKAnalyzer - - - - - - Using the package - - The following sections describe how to install and - use the package on Windows. - -
- - - Installation instructions - - - - Generating webhelp output - - - To install the package on Windows - - - The examples in this procedure assume a Windows installation, - but the process is the same in other environments, - mutatis mutandis. - - - - If necessary, install Java 1.6 or - higher. - - - - Confirm that Java is installed and in your - PATH by typing the following at a command prompt: - java -version - - To build the indexer, you must have the JDK. - - - - - - - If necessary, install Apache Ant 1.6.5 - or higher. - - - - Unzip the Ant binary distribution to a convenient location - on your system. For example: c:\Program - Files. - - - - Set the environment variable ANT_HOME to - the top-level Ant directory. For example: c:\Program - Files\apache-ant-1.7.1. - See How To Manage - Environment Variables in Windows XP for information - on setting environment variables. - - - - - Add the Ant bin directory to your - PATH. For example: c:\Program - Files\apache-ant-1.7.1\bin - - - - Confirm that Ant is installed by typing the following at a - command prompt: ant -version - - - If you see a message about the file - tools.jar being missing, you can safely - ignore it. - - - - - - - Download Saxon - 6.5.x and unzip the distribution to a convenient location on your file system. - You will use the path to saxon.jar in below. - The build.xml has only been tested with Saxon 6.5, though - it could be adapted to work with other XSLT processors. However, when you generate - output, the Saxon jar must not be in your - CLASSPATH. - - - - - In a text editor, edit the - build.properties file in the webhelp directory - and make the changes indicated by the comments:# The path (relative to the build.xml file) to your input document. -# To use your own input document, create a build.xml file of your own -# and import this build.xml. -input-xml=docsrc/readme.xml - -# The directory in which to put the output files. -# This directory is created if it does not exist. -output-dir=docs - -# If you are using a customization layer that imports webhelp.xsl, use -# this property to point to it. -stylesheet-path=${ant.file.dir}/xsl/webhelp.xsl - -# If your document has image directories that need to be copied -# to the output directory, you can list patterns here. -# See the Ant documentation for fileset for documentation -# on patterns. -#input-images-dirs=images/**,figures/**,graphics/** - -# By default, the ant script assumes your images are stored -# in the same directory as the input-xml. If you store your -# image directories in another directory, specify it here. -# and uncomment this line. -#input-images-basedir=/path/to/image/location - -# Modify this so that it points to your copy of the Saxon 6.5 jar. -xslt-processor-classpath=/usr/share/java/saxon-6.5.5.jar - -# For non-ns version only, this validates the document -# against a dtd. -validate-against-dtd=true - -# Set this to false if you don't need a search tab. -webhelp.include.search.tab=true - -# indexer-language is used to tell the search indexer which language -# the docbook is written. This will be used to identify the correct -# stemmer, and punctuations that differs from language to language. -# see the documentation for details. en=English, fr=French, de=German, -# zh=Chinese, ja=Japanese etc. -webhelp.indexer.language=en - - - - Test the package by running the command ant webhelp - -Doutput-dir=test-ouput at the command line in the webhelp directory. It should - generate a copy of this documentation in the doc - directory. Type start test-output\index.html to open the output in a - browser. Once you have confirmed that the process worked, you can delete the test-output directory. - The Saxon 6.5 jar should not be in your - CLASSPATH when you generate the webhelp output. If you have any - problems, try running ant with an empty CLASSPATH. - - - - - To process your own document, simply refer to this package - from another build.xml in arbitrary location on - your system: - - - - Create a new build.xml file that - defines the name of your source file, the desired output - directory, and imports the build.xml from - this package. For example: <project> - <property name="input-xml" value="path-to/yourfile.xml"/> - <property name="input-images-dirs" value="images/** figures/** graphics/**"/> - <property name="output-dir" value="path-to/desired-output-dir"/> - <import file="path-to/docbook-webhelp/build.xml"/> -</project> - - - - From the directory containing your newly created - build.xml file, type ant - webhelp to build your document. - - The Saxon 6.5 jar should not be in your - CLASSPATH when you generate the webhelp output. If you have any - problems, try running ant with an empty CLASSPATH. - - - - - -
- -
- Using and customizing the output - - To deep link to a topic inside the help set, simply link directly - to the page. This help system uses no frameset, so nothing further is - necessary. - See Chunking into - multiple HTML files in Bob Stayton's DocBook XSL: The - Complete Guide for information on controlling output file - names and which files are chunked in DocBook. - - - When you perform a search, the results can include brief - summaries. These are populated in one of two ways: - - By adding role="summary" to a - para or phrase in the - chapter or section. - - - - By adding an abstract to the - chapterinfo or sectioninfo - element. - - - - To customize the look and feel of the help, study the following - css files: - - docs/common/css/positioning.css: This - handles the Positioning of DIVs in appropriate positions. For - example, it causes the leftnavigation div to appear - on the left, the header on top, and so on. Use this if you need to - change the relative positions or need to change the width/height - etc. - - - - docs/common/jquery/theme-redmond/jquery-ui-1.8.2.custom.css: - This is the theming part which adds colors and stuff. This is a - default theme comes with jqueryui unchanged. You - can get any theme based your interest from this. (Themes are on - right navigation bar.) Then replace the css theme folder - (theme-redmond) with it, and change the xsl to point to the new - css. - - - - docs/common/jquery/treeview/jquery.treeview.css: - This styles the toc Tree. Generally, you don't have to edit this - file. - - - -
- Recommended Apache configurations - - If you are serving a long document from an Apache web server, we - recommend you make the following additions or changes to your - httpd.conf or .htaccess - file. TODO: Explain what each thing - does.AddDefaultCharSet UTF-8 # - - # 480 weeks - <FilesMatch "\.(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$"> # - Header set Cache-Control "max-age=290304000, public" - </FilesMatch> - - # 2 DAYS - <FilesMatch "\.(xml|txt)$"> - Header set Cache-Control "max-age=172800, public, must-revalidate" - </FilesMatch> - - # 2 HOURS - <FilesMatch "\.(html|htm)$"> - Header set Cache-Control "max-age=7200, must-revalidate" - </FilesMatch> - - # compress text, html, javascript, css, xml: - AddOutputFilterByType DEFLATE text/plain # - AddOutputFilterByType DEFLATE text/html - AddOutputFilterByType DEFLATE text/xml - AddOutputFilterByType DEFLATE text/css - AddOutputFilterByType DEFLATE application/xml - AddOutputFilterByType DEFLATE application/xhtml+xml - AddOutputFilterByType DEFLATE application/rss+xml - AddOutputFilterByType DEFLATE application/javascript - AddOutputFilterByType DEFLATE application/x-javascript - - # Or, compress certain file types by extension: - <Files *.html> - SetOutputFilter DEFLATE - </Files> - - - See Odd - characters in HTML output in Bob Stayton's book - DocBook XSL: The Complete Guide for more - information about this setting. - - - - 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. - - - - These lines cause the the server to compress html, css, - and JavaScript files and the brower to uncompress them to - improve download performance. - - -
-
- -
- Building the indexer - - To build the indexer, you must have installed the - JDK version 1.5 or higher and set the ANT_HOME - environment variable. Run ant build-indexer to recompile - nw-cms.jar - - - ANT_HOME - - - - indexer - - building - -
- -
- Adding support for other (non-CJKV) languages - - To support stemming for a language, the search mechanism requires - a stemmer implemented in both Java and JavaScript. The Java version is - used by the indexer and the JavaScript verison is used to stem the - user's input on the search form. Currently the search mechanism supports - stemming for English and German. In addition, Java stemmers are included - for the following languages. Therefore, to support these languages, you - only need to implement the stemmer in JavaScript and add it to the - template. If you do undertake this task, please consider contributing - the JavaScript version back to this project and to Martin - Porter's project. - - Danish - - - - Dutch - - - - Finnish - - - - Hungarian - - - - Italian - - - - Norwegian - - - - Portuguese - - - - Romanian - - - - Russian - - - - Spanish - - - - Swedish - - - - Turkish - - -
- - - - Developer Docs - - This chapter provides an overview of how webhelp is implemented. - - The table of contents and search panes are implemented as divs and - rendered as if they were the left pane in a frameset. As a result, the - page must save the state of the table of contents and the search in - cookies when you navigate away from a page. When you load a new page, the - page reads these cookies and restores the state of the table of contents - tree and search. The result is that the help system behaves exactly as if - it were a frameset. - -
- Design - An overview of webhelp page structure. - DocBook WebHelp page structure is fully built on css-based design - abandoning frameset structure. Overall page structure can be divided in to three main sections - - - Header: Header is a separate Div which include company logo, - navigation button(prev, next etc.), page title and heading of parent topic. - - - - Content: This includes the content of the documentation. The processing of this part is - done by - DocBook XSL Chunking customization. Few further css-styling applied from - positioning.css. - - - - - Left Navigation: This includes the table of contents and search tab. This - is customized using jquery-ui styling. - - - Tabbed Navigation: The navigation pane is organized in to two tabs. - Contents tab, and Search tab. Tabbed output is achieved using - JQuery Tabs plugin. - - - - - Table of Contents (TOC) tree: When building the chunked html from the - docbook file, Table of Contents is generated as an Unordered List (a list - made from <ul> <li> tags). When page loads in the browser, - we apply styling to it to achieve the nice look that you see. Styling for TOC - tree is done by a JQuery UI plugin called - - TreeView. We can generate the tree easily by following javascript code: - - -//Generate the tree -$("#tree").treeview({ -collapsed: true, -animated: "medium", -control: "#sidetreecontrol", -persist: "cookie" -}); - - - - - - Search Tab: This includes the search feature. - - - - - - -
- -
- Search - Overview design of Search mechanism. - - The searching is a fully client-side implementation of querying texts for - content searching, and no server is involved. That means when a user enters a query, - it is processed by JavaScript inside the browser, and displays the matching results by - comparing the query with a generated 'index', which too reside in the client-side web browser. - - Mainly the search mechanism has two parts. - - - Indexing: First we need to traverse the content in the docs/content folder and index - the words in it. This is done by nw-cms.jar. You can invoke it by - ant index command from the root of webhelp of directory. You can recompile it - again and build the jar file by ant build-indexer. Indexer has some extensive - support for such as stemming of words. Indexer has extensive support for English, German, - French languages. By extensive support, what I meant is that those texts are stemmed - first, to get the root word and then indexes them. For CJK (Chinese, Japanese, Korean) - languages, it uses bi-gram tokenizing to break up the words. (CJK languages does not have - spaces between words.) - - - When we run ant index, it generates five output files: - - - htmlFileList.js - This contains an array named fl which stores details - all the files indexed by the indexer. - - - - htmlFileInfoList.js - This includes some meta data about the indexed files in an array - named fil. It includes details about file name, file (html) title, a summary - of the content.Format would look like, - fil["4"]= "ch03.html@@@Developer Docs@@@This chapter provides an overview of how webhelp is implemented."; - - - - - index-*.js (Three index files) - These three files actually stores the index of the content. - Index is added to an array named w. - - - - - - - - - Querying: Query processing happens totally in client side. Following JavaScript files handles them. - - - nwSearchFnt.js - This handles the user query and returns the search results. It does query - word tokenizing, drop unnecessary punctuations and common words, do stemming if docbook language - supports it, etc. - - - {$indexer-language-code}_stemmer.js - This includes the stemming library. - nwSearchFnt.js file calls stemmer method in this file for stemming. - ex: var stem = stemmer(foobar); - - - - - - - - -
- New Stemmers - Adding new Stemmers is very simple. - Currently, only English, French, and German stemmers are integrated in to WebHelp. But the code is - extensible such that you can add new stemmers easily by few steps. - What you need: - - - You'll need two versions of the stemmer; One written in JavaScript, and another in Java. But fortunately, - Snowball contains Java stemmers for number of popular languages, and are already included with the package. - You can see the full list in Adding support for other (non-CJKV) languages. - If your language is listed there, - Then you have to find javascript version of the stemmer. Generally, new stemmers are getting added in to - Snowball Stemmers in other languages location. - If javascript stemmer for your language is available, then download it. Else, you can write a new stemmer in - JavaScript using SnowBall algorithm fairly easily. Algorithms are at - Snowball. - - - - Then, name the JS stemmer exactly like this: {$language-code}_stemmer.js. For example, - for Italian(it), name it as, it_stemmer.js. Then, copy it to the - docbook-webhelp/template/content/search/stemmers/ folder. (I assumed - docbook-webhelp is the root folder for webhelp.) - - Make sure you changed the webhelp.indexer.language property in build.properties - to your language. - - - - - - - - Now two easy changes needed for the indexer. - - - Open docbook-webhelp/indexer/src/com/nexwave/nquindexer/IndexerTask.java in - a text editor and add your language code to the supportedLanguages String Array. - - Add new language to supportedLanguages array - - change the Array from, - -private String[] supportedLanguages= {"en", "de", "fr", "cn", "ja", "ko"}; - //currently extended support available for - // English, German, French and CJK (Chinese, Japanese, Korean) languages only. - - To, - -private String[] supportedLanguages= {"en", "de", "fr", "cn", "ja", "ko", "it"}; - //currently extended support available for - // English, German, French, CJK (Chinese, Japanese, Korean), and Italian languages only. - - - - - - - Now, open docbook-webhelp/indexer/src/com/nexwave/nquindexer/SaxHTMLIndex.java and - add the following line to the code where it initializes the Stemmer (Search for - SnowballStemmer stemmer;). Then add code to initialize the stemmer Object in your language. - It's self understandable. See the example. The class names are at: - docbook-webhelp/indexer/src/com/nexwave/stemmer/snowball/ext/. - - - initialize correct stemmer based on the <code>webhelp.indexer.language</code> specified - - SnowballStemmer stemmer; - if(indexerLanguage.equalsIgnoreCase("en")){ - stemmer = new EnglishStemmer(); - } else if (indexerLanguage.equalsIgnoreCase("de")){ - stemmer= new GermanStemmer(); - } else if (indexerLanguage.equalsIgnoreCase("fr")){ - stemmer= new FrenchStemmer(); - } -else if (indexerLanguage.equalsIgnoreCase("it")){ //If language code is "it" (Italian) - stemmer= new italianStemmer(); //Initialize the stemmer to italianStemmer object. - } - else { - stemmer = null; - } - - - - - - - - That's all. Now run ant build-indexer to compile and build the java code. - Then, run ant webhelp to generate the output from your docbook file. - For any questions, contact us or email to the docbook mailing list - docbook-apps@lists.oasis-open.org. - -
-
- -