From: David Cramer Date: Sun, 16 Dec 2012 02:54:55 +0000 (+0000) Subject: Webhelp: Documentation updates. X-Git-Tag: release/1.79.1~6^2~260 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=2b303ec8b39b86e7571fe45b65baaf613d99e56e;p=docbook-dsssl Webhelp: Documentation updates. --- diff --git a/xsl/webhelp/docsrc/readme.xml b/xsl/webhelp/docsrc/readme.xml index c092dd9b3..6a75161dd 100644 --- a/xsl/webhelp/docsrc/readme.xml +++ b/xsl/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. - This package is maintained by Kasun Gajasinghe, kasunbg AT gmail DOT com - and David Cramer, david AT thingbag DOT net. + This package is maintained by Kasun Gajasinghe, + kasunbg AT gmail DOT com and David Cramer, + david AT thingbag DOT net and with + contributions by Arun Bharadwaj and Visitha Baddegama. Please + direct support questions to the DocBook-apps + mailing list. This package also includes the following software written and copyrighted by others: Files in template/common/jquery are @@ -65,12 +70,16 @@ - 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. + Some files in the template/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 @@ -95,6 +104,12 @@ Ltd., the publishers of the oXygen XML Editor. + + TagSoup, released under the Apache 2.0 + license, makes it possible to index html instead of just + xhtml output. + Cosmetic improvements provided by TOC and search pane implemented without the use of a frameset. - 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 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 Docbkx Maven plugin. - Using the package The following sections describe how to - install and use the package on Windows. + 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 + Makefile.sample as a starting point for + creating your build script. To use + Makefile.sample you must have + xsltproc and java + available in your PATH.
Installation instructions - Generating webhelp output + Generating webhelp output using the Ant build.xml + file To install the package on Windows @@ -332,14 +307,6 @@ CLASSPATH. - In a text editor, edit the build.properties file in the @@ -382,7 +349,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 +# 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 +357,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 - + # For non-ns version only, this validates the document # against a dtd. validate-against-dtd=true @@ -417,16 +384,15 @@ admon.graphics=0 suppress.footer.navigation=0 - 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. - + 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. To process your own document, simply refer to this package from another @@ -496,10 +462,10 @@ suppress.footer.navigation=0
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 # + 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. AddDefaultCharSet UTF-8 # # 480 weeks <FilesMatch "\.(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$"> # @@ -533,19 +499,25 @@ suppress.footer.navigation=0 </Files> - See Odd - characters in HTML output in Bob Stayton's book DocBook XSL: - The Complete Guide for more information about this setting. + 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 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. + These lines cause the the server to compress html, + css, and JavaScript files and the brower to uncompress + them to improve download performance.
@@ -796,19 +768,26 @@ persist: "cookie" a simplified 'index' that too resides in JavaScript. 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 webhelpindexer.jar in - xsl/extentions/ folder. You can invoke it by ant - index command from the root of webhelp of directory. The source of + Indexing: First we need to traverse the content in + the docs folder and index the words in it. This is done + by webhelpindexer.jar in + xsl/extentions/ folder. You can + invoke it by ant index command from the + root of webhelp of directory. The source of webhelpindexer is now moved to it's own location at - trunk/xsl-webhelpindexer/. Checkout the Docbook trunk svn - directory to get this source. Then, do your changes and recompile it by simply running - ant 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). + trunk/xsl-webhelpindexer/. + Checkout the Docbook trunk svn directory to get this + source. Then, do your changes and recompile it by simply + running ant 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). When ant index is run, it generates five output files: htmlFileList.js - This contains an array named @@ -817,11 +796,14 @@ persist: "cookie" to false. - 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."; + 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."; @@ -875,12 +857,18 @@ persist: "cookie" 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. + {$language-code}_stemmer.js. + For example, for Italian(it), name it as, + it_stemmer.js. Then, copy it to + the + docbook-webhelp/template/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.