From: Bob Stayton Date: Fri, 21 Feb 2014 22:14:09 +0000 (+0000) Subject: Convert XML doc to DB5. X-Git-Tag: release/1.79.1~6^2~66 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=529b861b03d133032921e4609d3fdbaeeb320b20;p=docbook-dsssl Convert XML doc to DB5. --- diff --git a/xsl/webhelp/docsrc/readme.xml b/xsl/webhelp/docsrc/readme.xml index ea4896976..ba965a008 100644 --- a/xsl/webhelp/docsrc/readme.xml +++ b/xsl/webhelp/docsrc/readme.xml @@ -1,25 +1,7 @@ - - - - - - - - -]> - + + 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 @@ -56,13 +38,12 @@ 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. + 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 - copyrighted by JQuery under the MIT License. + copyrighted by JQuery under the MIT License. The file jquery.cookie.js Copyright (c) 2006 Klaus Hartl under the MIT license. @@ -70,13 +51,9 @@ - Some files in the template/search and indexer directories were + 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 + 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. @@ -88,61 +65,47 @@ - Stemmers from the Snowball - project released under a BSD license. + Stemmers from the Snowball + project released under a BSD license. - Code from the Apache Lucene search + Code from the Apache Lucene search engine provides support for tokenizing Chinese, Japanese, and Korean content released under the Apache 2.0 license. Code that provides weighted search results and some - other improvements was graciously donated by SyncRO Soft - Ltd., the publishers of the oXygen XML + other improvements was graciously donated by SyncRO Soft + Ltd., the publishers of the oXygen XML Editor. - TagSoup, released under the Apache 2.0 + TagSoup, released under the Apache 2.0 license, makes it possible to index html instead of just xhtml output. - Cosmetic improvements provided by OpenStack. + Cosmetic improvements provided by OpenStack. - Webhelp for DocBook was first developed as a Google Summer of Code project. + Webhelp for DocBook was first developed as a Google Summer of Code project. 2008-2012 Kasun Gajasinghe David Cramer - - David - Cramer - david AT thingbag DOT net - - - Kasun - Gajasinghe - kasunbg AT gmail DOT com - + DavidCramerdavid AT thingbag DOT net + KasunGajasinghekasunbg AT gmail DOT com January 2012 - + - + Introduction 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 @@ -172,8 +135,7 @@ search-result. - Search results can include brief descriptions of the target. + Search results can include brief descriptions of the target. search description @@ -217,9 +179,7 @@ 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. + the Docbkx Maven plugin. @@ -235,13 +195,13 @@ xsltproc and java available in your PATH.
- + Generating webhelp output using the Ant build.xml + file Installation instructions - - Generating webhelp output using the Ant build.xml - file + + To install the package @@ -255,15 +215,13 @@ Makefile.sample you must have xsltproc and java available in your PATH. You can also use - the Docbkx Maven plugin to generate webhelp. + the Docbkx Maven plugin to generate webhelp. - - If necessary, install Java - 1.6 or higher. - - + + 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 @@ -272,28 +230,27 @@ - - If necessary, install Apache - Ant 1.8.0 or higher. See Ant installation instructions. - - + + If necessary, install Apache + Ant 1.8.0 or higher. See Ant installation instructions. + + 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.8.0. - See How To Manage - Environment Variables in Windows XP for information on setting + 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.8.0\bin - + Confirm that Ant is installed by typing the following at a command prompt: ant -version @@ -303,27 +260,25 @@ - - 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. + + 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. - - Download Xerces2 - Java and extract it to a convenient location on + + Download Xerces2 + Java and extract it to a convenient location on your file system. You will need the xercesImpl.jar and xml-apis.jar from this distribution in in . - + In a text editor, edit the build.properties file in the webhelp directory and make the changes indicated by the comments. @@ -331,9 +286,8 @@ xslt-processor-classpath, xercesImpl.jar, and xml-apis.jar. - See the DocBook reference - documentation for detailed information about the + See the DocBook reference + documentation for detailed information about the available webhelp and other parameters. Note that not all DocBook parameters are passed in to the xsls by the build.xml by default. You may need @@ -399,22 +353,20 @@ enable.stemming=true 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 + 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. + you can delete the test-output directory. - + 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: @@ -425,7 +377,7 @@ suppress.footer.navigation=0 <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. @@ -437,22 +389,21 @@ suppress.footer.navigation=0 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 + 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 role="summary" to a para or + phrase in the chapter or + section. - By adding an abstract to the chapterinfo or - sectioninfo element. + By adding an abstract to the chapterinfo or + sectioninfo element. To customize the look and feel of the help, study the following css files: @@ -466,7 +417,7 @@ suppress.footer.navigation=0 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 + 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. @@ -481,10 +432,10 @@ suppress.footer.navigation=0 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 # + .htaccess file. AddDefaultCharSet UTF-8 # # 480 weeks - <FilesMatch "\.(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$"> # + <FilesMatch "\.(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$"> # Header set Cache-Control "max-age=290304000, public" </FilesMatch> @@ -499,7 +450,7 @@ suppress.footer.navigation=0 </FilesMatch> # compress text, html, javascript, css, xml: - AddOutputFilterByType DEFLATE text/plain # + AddOutputFilterByType DEFLATE text/plain # AddOutputFilterByType DEFLATE text/html AddOutputFilterByType DEFLATE text/xml AddOutputFilterByType DEFLATE text/css @@ -515,9 +466,7 @@ suppress.footer.navigation=0 </Files> - See Odd characters in HTML output in Bob + See Odd characters in HTML output in Bob Stayton's book DocBook XSL: The Complete Guide for more information about this setting. @@ -624,9 +573,8 @@ suppress.footer.navigation=0 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. + consider contributing the JavaScript version back to this project and to Martin Porter's + project. Danish @@ -676,8 +624,7 @@ suppress.footer.navigation=0 Then refer to those images from your docbook document. - Following image is from webhelp/docsrs/images/sample.jpg. The docbook code is shown + Following image is from webhelp/docsrs/images/sample.jpg. The docbook code is shown below.
@@ -691,14 +638,14 @@ suppress.footer.navigation=0 Example code for adding images. Note down the relative path used - <figure> - <title>Sample</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/sample.jpg" format="JPG"/> - </imageobject> - </mediaobject> -</figure> + <figure> + <title>Sample</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/sample.jpg" format="JPG"/> + </imageobject> + </mediaobject> +</figure> @@ -732,28 +679,25 @@ input-images-dirs=images/**,figures/**,graphics/** 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 + 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. + 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. + 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 + <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: + by a JQuery UI plugin called + TreeView. We can generate the tree easily by following javascript code: //Generate the tree $("#tree").treeview({ @@ -862,14 +806,12 @@ persist: "cookie" 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. + 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 + 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. + SnowBall algorithm fairly easily. Algorithms are at Snowball. Then, name the JS stemmer exactly like this: @@ -956,12 +898,12 @@ private String[] supportedLanguages= {"en", "de", "fr", "cn", "ja", "ko", - + FAQ Frequently Asked Questions - - FAQ + + @@ -979,8 +921,7 @@ private String[] supportedLanguages= {"en", "de", "fr", "cn", "ja", "ko", - There are four production deployments provided in WebHelp wiki currently. + There are four production deployments provided in WebHelp wiki currently. @@ -1015,9 +956,7 @@ xml-apis.jar=/usr/share/java/xml-apis.jar I need more information about webhelp-indexer. Where can I find it? - The DocBook Webhelp Indexer is based on the HTMLSearch plugin for DITA. See HTMLSearch documentation for more information. + The DocBook Webhelp Indexer is based on the HTMLSearch plugin for DITA. See HTMLSearch documentation for more information. @@ -1025,6 +964,6 @@ xml-apis.jar=/usr/share/java/xml-apis.jar FAQ - + diff --git a/xsl/webhelp/docsrc/xinclude-test.xml b/xsl/webhelp/docsrc/xinclude-test.xml index 77ef4f88e..e8a64f03d 100644 --- a/xsl/webhelp/docsrc/xinclude-test.xml +++ b/xsl/webhelp/docsrc/xinclude-test.xml @@ -1,6 +1,5 @@ - - + + Test section
Some search words for testing @@ -10,4 +9,4 @@ Some search words for testing (inflected) arsenal, arsenic, buys, says, varies, tries, skies, nuclei, days, keys, currencies, build.xml
- \ No newline at end of file +