From 040e0f4c0dc0f4959a4854c725640b884608493d Mon Sep 17 00:00:00 2001 From: David Cramer Date: Mon, 19 Jul 2010 01:55:10 +0000 Subject: [PATCH] Documentation updates --- xsl/webhelp/build.properties | 5 +- xsl/webhelp/docsrc/readme.xml | 270 ++++++++++++++++++++++++++-------- 2 files changed, 210 insertions(+), 65 deletions(-) diff --git a/xsl/webhelp/build.properties b/xsl/webhelp/build.properties index 67bd6f776..484a0cc09 100755 --- a/xsl/webhelp/build.properties +++ b/xsl/webhelp/build.properties @@ -29,7 +29,8 @@ xslt-processor-classpath=c:/workhead/export/saxon/6.5/lib/saxon.jar # To use this catalog, make sure the resolver is in your classpath. # Download xml-commons-resolver from http://xml.apache.org/commons/dist/ # and add it to your CLASSPATH. Then use the following property to point -# to your docbook xsl stylesheets' catalog +# to your docbook xsl stylesheets' catalog. Alternatively, +# you can list the catalog file in your CatalogManager.properties file. docbook-xsl-catalog=c:/gsoc2010/docbook-xsl-1.75.2/catalog.xml #docbook-xsl-catalog=/media/DATA/ACADEMIC/GSOC/docbook/repository/docbook/trunk/maven/docbook-xsl/target/xsltmp/docbook-xsl-1.75.2/catalog.xml @@ -37,6 +38,8 @@ docbook-xsl-catalog=c:/gsoc2010/docbook-xsl-1.75.2/catalog.xml # building it, set this property to the location # of your DocBook DTD. The sample document is # a DocBook 4.5 document and uncomment the line validate=true. +# Alternatively, you can list the DTD's catalog file in your +# CatalogManager.properties file. docbookx.dtd=c:/workhead/export/DocBookDTD/4.5/docbookx.dtd #docbookx.dtd=file:///media/DATA/ACADEMIC/GSOC/docbook/repository/docbook/trunk/defguide/en/schema/docbookx.dtd validate=true diff --git a/xsl/webhelp/docsrc/readme.xml b/xsl/webhelp/docsrc/readme.xml index 4e43fdaa6..d1626d0eb 100755 --- a/xsl/webhelp/docsrc/readme.xml +++ b/xsl/webhelp/docsrc/readme.xml @@ -418,19 +418,6 @@ - - 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 @@ -461,36 +448,71 @@ - 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. - + To improve performance, you should use a catalog resolver to + cause webhelp.xsl to import a local version of the DocBook XSL + stylesheets. Alternatively, you can edit the href attribute in the + xsl:import element in + webhelp.xsl. + + + + 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 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 + 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=doc -stylesheet-path=xsl/webhelp.xsl + +# 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/** +#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. +# 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. @@ -499,14 +521,19 @@ xslt-processor-classpath=c:/workhead/export/saxon/6.5/lib/saxon.jar # To use this catalog, make sure the resolver is in your classpath. # Download xml-commons-resolver from http://xml.apache.org/commons/dist/ # and add it to your CLASSPATH. Then use the following property to point -# to your docbook xsl stylesheets' catalog +# to your docbook xsl stylesheets' catalog. Alternatively, +# you can list the catalog file in your CatalogManager.properties file. docbook-xsl-catalog=c:/gsoc2010/docbook-xsl-1.75.2/catalog.xml +#docbook-xsl-catalog=/media/DATA/ACADEMIC/GSOC/docbook/repository/docbook/trunk/maven/docbook-xsl/target/xsltmp/docbook-xsl-1.75.2/catalog.xml # If you wish to have the ant script validate the document before # building it, set this property to the location # of your DocBook DTD. The sample document is # a DocBook 4.5 document and uncomment the line validate=true. +# Alternatively, you can list the DTD's catalog file in your +# CatalogManager.properties file. docbookx.dtd=c:/workhead/export/DocBookDTD/4.5/docbookx.dtd +#docbookx.dtd=file:///media/DATA/ACADEMIC/GSOC/docbook/repository/docbook/trunk/defguide/en/schema/docbookx.dtd validate=true # Set this to true if you don't need a search tab. @@ -531,11 +558,13 @@ indexer-language=en - To process your own content: + To process your own content you simply refer to this package + from another build.xml in arbitrary location on + your system. - create a new build.xml file that + 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> @@ -585,16 +614,88 @@ indexer-language=en - TODO: Document Apache config changes to improve performance of - very long documents. + To customize the look and feel of the help, study the following + css files: + + doc/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. + + + + doc/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. + + + + doc/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> + +ErrorDocument 404 http://www.thingbag.net/404.html + +IndexIgnore * + +# 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> + +
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 + JDK version 1.5 or higher and set the ANT_HOME + environment variable. Run ant build-indexer to recompile nw-cms.jar @@ -609,45 +710,86 @@ indexer-language=en
- Adding support for other languages + 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 + - Currently, -
- + + Dutch + - - Design + + Finnish + - This chapter provides an overview of how webhelp is implemented. - WRITEME + + French + - TODO: Document details about cookie use. - + + Hungarian + - - - - Demo of Japanese text: - ネットワークに接続されているコンピュータ。加入者コンピュータはクライアント - ホストであり、プロバイダ システムはサーバー ホストです。 - - + + Italian + - ホスト + + Norwegian + - - ホスト - + + Portuguese + - To test this page, search for the term: ホスト + + Romanian + - - ホスト + + Russian + + + + Spanish + - ネットワークに接続されているコンピュータ。加入者コンピュータはクライアント - ホストであり、プロバイダ システムはサーバー ホストです。 - + + Swedish + + + + Turkish + + + - + + Design + + This chapter provides an overview of how webhelp is implemented. + WRITEME + + 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. + -- 2.40.0