From: David Cramer Date: Sun, 18 Jul 2010 04:25:31 +0000 (+0000) Subject: Copy doc images from source tree if they're in a folder named images. Only copy the... X-Git-Tag: release/1.79.1~6^2~831^2~58 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=8733ea4b8dd5dea6efe1a66d2268b1e1b8564b75;p=docbook-dsssl Copy doc images from source tree if they're in a folder named images. Only copy the *.props file, default.props, and punctuation.props, not all of them --- diff --git a/xsl/webhelp/build.xml b/xsl/webhelp/build.xml index 2326e3376..f7566c31e 100755 --- a/xsl/webhelp/build.xml +++ b/xsl/webhelp/build.xml @@ -1,125 +1,141 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Indexing html files in ${frameset.base.dir}/content - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Usage: - doc: Generate the documentation in the doc dir and index it. - chunk: Generate the frameset. - index: Index the content. - build-indexer: Rebuilds the indexer. - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Indexing html files in ${frameset.base.dir}/content + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Usage: + doc: Generate the documentation in the doc dir and index it. + chunk: Generate the frameset. + index: Index the content. + build-indexer: Rebuilds the indexer. + diff --git a/xsl/webhelp/docsrc/readme.xml b/xsl/webhelp/docsrc/readme.xml index 9062d9deb..ccad9f369 100755 --- a/xsl/webhelp/docsrc/readme.xml +++ b/xsl/webhelp/docsrc/readme.xml @@ -1,280 +1,436 @@ - - + + Web-based Help from DocBook XML Readme + 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: + 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. + 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. + 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 publically - 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. + 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 NORMAN WALSH 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. + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. + IN NO EVENT SHALL NORMAN WALSH 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: + + 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. + 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 + - All files in template/content/search and indexer are part of N. Quaine's htmlsearch DITA plugin, with modifications to fix bugs and make it work better with DocBook content. 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 - - + All files in template/content/search and indexer are part of N. Quaine's + htmlsearch DITA plugin, with modifications to fix bugs and make it + work better with DocBook content. 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 + - - + + Version .01/Alpha + 2008-2010 - Kasun Gajasinghe + + Kasun Gajasinghe + David Cramer + David + Cramer + dcramer AT motive DOT com + david AT thingbag DOT net - - Kasun - Gajasinghe - kasunbg AT gmail DOT com - + + + Kasun + + Gajasinghe + + kasunbg AT gmail DOT com + + July 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. - + + 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 + + + Full text search with stemming support for English and German. + Stemming support can be added for other languages if a stemmer is + implemented. + + + + Search results can include brief descriptions of the + target. + + Table of contents pane with collapsable toc tree. + + + Autosynchronization of content pane and TOC. + + - Full-text search. Search results can include brief descriptions of the target. + TOC and search pane implemented without the use of a frameset. + + - Support for deep linking by simply linking to the page since no frameset is used. + 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. + + Enhancements planned as part of GSOC 2010 + - 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. + [DONE] Implement the toc and serach pane without using + frames. - - - - Enhancements planned as part of GSOC 2010 - - Add stemmming support for English and one major non-Asian language. - - - Improve the support for Japanese and Chinese. - - - Search highlighting. - - - Documentation for skinning and customization options. - - - A show/hide toc button. - - - Parameterize width of the TOC pane OR make the TOC pane resizable by the user. - - - Support for ns and non-ns DocBook stylesheets. - - - Skipping of next and prev links in the footer and header. - - - Moving of the header Next and Prev links to the banner - - - + + + [DONE] Move the header Next and Prev links to the + banner + + + + [DONE] Make indexer skip next and prev links in the footer and + header. + + + + Improve the support for Japanese and Chinese. + + + + Add search highlighting. + + + + Document skinning and customization options. + + + + Support 5.x/ns and 4.x/non-ns DocBook stylesheets. + + Future enhancements - - Add "Expand all" and "Collapse all" buttons to the toc. - - - Add an option to use Lucene for server-side searches with toc state persisted on the server. - - - Sort search results based on relevance - + + + Add "Expand all" and "Collapse all" buttons to the toc. + + + + Add an option to use Lucene for server-side searches with toc + state persisted on the server. + + - 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. - - + Sort search results based on relevance + + + Parameterize width of the TOC pane OR make the TOC pane + resizable 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. - - 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. - + + + 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 a parameter to make it possible to disable the search tab + if it is not required. + + - 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 (optional) index tab populated by a separate JavaScript + file. - - Add a parameter to make it possible to disable the search tab if it is not required. - - - Add an (optional) index tab populated by a separate JavaScript file. - - - + + Using the package - The following sections describe how to install and use the package on Windows. + + The following sections describe how to install and + use the package on Windows. +
Installation instructions - Installation + + Obtaining, installing, and running the package + 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.5 or higher. - - - Confirm that Java is installed and in your PATH by typing the following at a command prompt: java -version - - - + + + 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.5 or + higher. + + + + Confirm that Java is installed and in your + PATH by typing the following at a command prompt: + java -version + + + + + + 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. + + + + + - 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. - - - + If necessary, download xml-commons-resolver.jar + and add it to your CLASSPATH. + When adding jar files to your CLASSPATH, be + sure to include the jar file. For example: + C:\programs\xml-commons-resolver-1.2\resolver.jar. + Note that on Windows, the CLASSPATH is a + semicolon delimited list of jar files and paths to java class + files. + + - If necessary, download xml-commons-resolver.jar and add it to your CLASSPATH. - - When adding jar files to your CLASSPATH, be sure to include the jar file. For example: C:\programs\xml-commons-resolver-1.2\resolver.jar. Note that on Windows, the CLASSPATH is a semicolon delimited list of jar files and paths to java class files. - - + Download Saxon + 6.5.x and unzip the distribution to a convenient location on + your filesystem. 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 filesystem. You will use the path to saxon.jar in below. - + - Obtain the package. Currently, the webhelp package is only available through Subversion. - - - If necessary, install a Subversion client. - - - In a convenient location on your system, run the command svn co https://docbook.svn.sourceforge.net/svnroot/docbook/branches/webhelp/xsl/webhelp webhelp - - + Obtain the package in one of two ways: + + + + Download the beta + version of the package. + + + + OR, if you prefer to have the bleeding edge, you can use a + Subversion + client to download it directly from Subversion: + svn co https://docbook.svn.sourceforge.net/svnroot/docbook/branches/webhelp/xsl/webhelp webhelp + + - - To improve performance, download and extract DocBook XSLs to a convenient location on your file system. Currently, this package supports docbook-xsl (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. - - If you see the message Warning: catalogpath listing external catalogs will be ignored when you generate output, this indicates that your catalog resolver is not installed correctly and is not being used. - - - - - In a text editor, edit the build.properties file in the webhelp directory and make the changes indicated by the comments:input-xml=docsrc/readme.xml + + + To improve performance, download and extract DocBook XSLs to a + convenient location on your file system. Currently, this package + supports docbook-xsl + (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. + If you see the message Warning: catalogpath listing external catalogs will be ignored + when you generate output, this indicates that your catalog + resolver is not installed correctly and is not being + used. + + + + + In a text editor, edit the + build.properties file in the webhelp directory + and make the changes indicated by the comments:input-xml=docsrc/readme.xml frameset.base.dir=doc # Modify this so that it points to your copy of the Saxon 6.5 jar. @@ -300,82 +456,132 @@ exclude.search.from.chunked.html=false #This will be used to identify the correct stemmer, and punctuations that differs from language to language. #see the documentation for details. en=English, cn=Chinese, jp=Japanese etc. indexer-language=en - + + - Test the package by running the command ant webhelp at the command line in the webhelp directory. It should generate a copy of this documentation in the doc directory. Type start doc\index.html to open the output in a browser. + Test the package by running the command ant + webhelp at the command line in the webhelp directory. It + should generate a copy of this documentation in the doc directory. Type start + doc\index.html to open the output in a browser. + - To process your own content: - - - - 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="frameset.base.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. - - - Add some code to the main ant script to copy your images to the output directory. - - - + To process your own content: + + + + 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="frameset.base.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. + + + + Add some code to the main ant script to copy your images + to the output directory. + + +
+
- 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 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. - - - - TODO: Document Apache config changes to improve performance of very long documents. + 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 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. + + + + TODO: Document Apache config changes to improve performance of + very long documents.
+
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 + + 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
+ - Design - This chapter provides an overview of how webhelp is implemented. WRITEME - TODO: Document details about cookie use. + Design + + This chapter provides an overview of how webhelp is implemented. + WRITEME + + TODO: Document details about cookie use. + - - - Demo of Japanese text: ネットワークに接続されているコンピュータ。加入者コンピュータはクライアント ホストであり、プロバイダ システムはサーバー ホストです。 - - - ホスト - - ホスト - - To test this page, search for the term: ホスト - - ホスト - ネットワークに接続されているコンピュータ。加入者コンピュータはクライアント ホストであり、プロバイダ システムはサーバー ホストです。 - + + + Demo of Japanese text: + ネットワークに接続されているコンピュータ。加入者コンピュータはクライアント + ホストであり、プロバイダ システムはサーバー ホストです。 + + + + ホスト + + + ホスト + + + To test this page, search for the term: ホスト + + + ホスト + + ネットワークに接続されているコンピュータ。加入者コンピュータはクライアント + ホストであり、プロバイダ システムはサーバー ホストです。 + - + +