doc/xslt/webhelp/docs/content/ch02s01.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xmlns:exsl="http://exslt.org/common" xmlns:ng="http://docbook.org/docbook-ng" xmlns:db="http://docbook.org/ns/docbook"><head>
   4 <meta http-equiv="X-UA-Compatible" content="IE=7" />
   5 <title>Generating webhelp output</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><meta name="description" content="Installation instructions" /><link rel="home" href="index.html" title="README: Web-based Help from DocBook XML" /><link rel="up" href="ch02.html" title="Chapter 2. Using the package" /><link rel="prev" href="ch02.html" title="Chapter 2. Using the package" /><link rel="next" href="ch02s02.html" title="Using and customizing the output" /><meta http-equiv="Content-Type" content="text/html; charset=utf-8" /><script type="text/javascript">
   6             //The id for tree cookie
   7             var treeCookieId = "treeview-897";
   8             var language = "en";
   9             var w = new Object();
  10             //Localization
  11             txt_filesfound = 'Results';
  12             txt_enter_at_least_1_char = "You must enter at least one character.";
  13             txt_browser_not_supported = "Your browser is not supported. Use of Mozilla Firefox is recommended.";
  14             txt_please_wait = "Please wait. Search in progress...";
  15             txt_results_for = "Results for: ";
  16         </script><style type="text/css">
  17             input {
  18             margin-bottom: 5px;
  19             margin-top: 2px;
  20             }
  21
  22             .folder {
  23             display: block;
  24             height: 22px;
  25             padding-left: 20px;
  26             background: transparent url(../common/jquery/treeview/images/folder.gif) 0 0px no-repeat;
  27             }
  28             </style><link rel="shortcut icon" href="../favicon.ico" type="image/x-icon" /><link rel="stylesheet" type="text/css" href="../common/css/positioning.css" /><link rel="stylesheet" type="text/css" href="../common/jquery/theme-redmond/jquery-ui-1.8.2.custom.css" /><link rel="stylesheet" type="text/css" href="../common/jquery/treeview/jquery.treeview.css" /><script type="text/javascript" src="../common/jquery/jquery-1.4.2.min.js"></script><script type="text/javascript" src="../common/jquery/jquery-ui-1.8.2.custom.min.js"></script><script type="text/javascript" src="../common/jquery/jquery.cookie.js"></script><script type="text/javascript" src="../common/jquery/treeview/jquery.treeview.min.js"></script><script type="text/javascript" src="search/htmlFileList.js"></script><script type="text/javascript" src="search/htmlFileInfoList.js"></script><script type="text/javascript" src="search/nwSearchFnt.js"></script><script type="text/javascript" src="search/stemmers/en_stemmer.js"><!--//make this scalable to other languages as well.--></script><script type="text/javascript" src="search/index-1.js"></script><script type="text/javascript" src="search/index-2.js"></script><script type="text/javascript" src="search/index-3.js"></script></head><body><div id="header"><img style="margin-right: 2px; height: 59px; padding-right: 25px; padding-top: 8px" align="right" src="../common/images/logo.png" alt="Company Logo" /><h1 align="center">Generating webhelp output<br />Chapter 2. Using the package</h1><div id="navheader" align="right"><table><tr><td style="height: 28px; width: 16px;"><a id="showHideButton" onclick="showHideToc();" class="pointLeft" title="Hide TOC tree">.
  29                             </a></td><td><img src="../common/images/highlight-blue.gif" alt="H" height="25px" onclick="toggleHighlight()" id="showHideHighlight" style="cursor:pointer" title="Toggle search result highlighting" /></td><td><a accesskey="p" href="ch02.html">Prev</a>
  30                                         |
  31                                         <a accesskey="u" href="ch02.html">Up</a>
  32                                     |
  33                                     <a accesskey="n" href="ch02s02.html">Next</a></td></tr></table></div></div><div id="content"><div class="section" title="Generating webhelp output"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id36123640"></a>Generating webhelp output</h2></div><div><div class="abstract" title="Abstract"><p class="title"><strong>Abstract</strong></p><p>Installation instructions</p></div></div></div></div><div class="procedure" title="Procedure 2.1. To install the package on Windows"><a id="id36123655"></a><p class="title"><strong>Procedure 2.1. To install the package on Windows</strong></p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The examples in this procedure assume a Windows installation,
  34           but the process is the same in other environments,
  35           <span class="foreignphrase"><em class="foreignphrase">mutatis mutandis</em></span>.</p></div><ol class="procedure" type="1"><li class="step" title="Step 1"><p>If necessary, install <a class="ulink" href="http://www.java.com/en/download/manual.jsp" target="_top">Java 1.6</a> or
  36           higher.</p><ol type="a" class="substeps"><li class="step" title="Step 1.a"><p>Confirm that Java is installed and in your
  37               <code class="envar">PATH</code> by typing the following at a command prompt:
  38               </p><pre class="programlisting">java -version</pre><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>To build the indexer, you must have the JDK.</p></div></li></ol></li><li class="step" title="Step 2"><p>If necessary, install <a class="ulink" href="http://ant.apache.org/bindownload.cgi" target="_top">Apache Ant</a> 1.6.5
  39           or higher.</p><ol type="a" class="substeps"><li class="step" title="Step 2.a"><p>Unzip the Ant binary distribution to a convenient location
  40               on your system. For example: <code class="filename">c:\Program
  41               Files</code>.</p></li><li class="step" title="Step 2.b"><p>Set the environment variable <code class="envar">ANT_HOME</code> to
  42               the top-level Ant directory. For example: <code class="filename">c:\Program
  43               Files\apache-ant-1.7.1</code>. </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>See <a class="ulink" href="http://support.microsoft.com/kb/310519" target="_top">How To Manage
  44                   Environment Variables in Windows XP</a> for information
  45                   on setting environment variables.</p></div></li><li class="step" title="Step 2.c"><p>Add the Ant <code class="filename">bin</code> directory to your
  46               <code class="envar">PATH</code>. For example: <code class="filename">c:\Program
  47               Files\apache-ant-1.7.1\bin</code></p></li><li class="step" title="Step 2.d"><p>Confirm that Ant is installed by typing the following at a
  48               command prompt: </p><pre class="programlisting">ant -version</pre><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If you see a message about the file
  49                 <code class="filename">tools.jar</code> being missing, you can safely
  50                 ignore it.</p></div></li></ol></li><li class="step" title="Step 3"><p>Download <a class="ulink" href="http://prdownloads.sourceforge.net/saxon/saxon6-5-5.zip" target="_top">Saxon
  51               6.5.x</a> and unzip the distribution to a convenient location on your file system.
  52             You will use the path to <code class="filename">saxon.jar</code> in <a class="xref" href="ch02s01.html#edit-build-properties" title="Step 4">Step 4</a> below.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The <code class="filename">build.xml</code> has only been tested with Saxon 6.5, though
  53                 it could be adapted to work with other XSLT processors. However, when you generate
  54                 output, the Saxon jar must <span class="bold"><strong>not</strong></span> be in your
  55                   <code class="envar">CLASSPATH</code>.</p></div></li><li class="step" title="Step 4"><a id="edit-build-properties"></a><p>In a text editor, edit the
  56           <code class="filename">build.properties</code> file in the webhelp directory
  57           and make the changes indicated by the comments:</p><pre class="programlisting"># The path (relative to the build.xml file) to your input document.
  58 # To use your own input document, create a build.xml file of your own
  59 # and import this build.xml.
  60 input-xml=docsrc/readme.xml
  61
  62 # The directory in which to put the output files.
  63 # This directory is created if it does not exist.
  64 output-dir=docs
  65
  66 # If you are using a customization layer that imports webhelp.xsl, use
  67 # this property to point to it.
  68 stylesheet-path=${ant.file.dir}/xsl/webhelp.xsl
  69
  70 # If your document has image directories that need to be copied
  71 # to the output directory, you can list patterns here.
  72 # See the Ant documentation for fileset for documentation
  73 # on patterns.
  74 #input-images-dirs=images/**,figures/**,graphics/**
  75
  76 # By default, the ant script assumes your images are stored
  77 # in the same directory as the input-xml. If you store your
  78 # image directories in another directory, specify it here.
  79 # and uncomment this line.
  80 #input-images-basedir=/path/to/image/location
  81
  82 # Modify this so that it points to your copy of the Saxon 6.5 jar.
  83 xslt-processor-classpath=/usr/share/java/saxon-6.5.5.jar
  84
  85 # For non-ns version only, this validates the document
  86 # against a dtd.
  87 validate-against-dtd=true
  88
  89 # Set this to false if you don't need a search tab.
  90 webhelp.include.search.tab=true
  91
  92 # indexer-language is used to tell the search indexer which language
  93 # the docbook is written.  This will be used to identify the correct
  94 # stemmer, and punctuations that differs from language to language.
  95 # see the documentation for details. en=English, fr=French, de=German,
  96 # zh=Chinese, ja=Japanese etc.
  97 webhelp.indexer.language=en</pre></li><li class="step" title="Step 5"><p>Test the package by running the command <code class="code">ant webhelp
  98               -Doutput-dir=test-ouput</code> at the command line in the webhelp directory. It should
  99             generate a copy of this documentation in the <code class="filename">doc</code>
 100             directory. Type <code class="code">start test-output\index.html</code> to open the output in a
 101             browser. Once you have confirmed that the process worked, you can delete the <code class="filename">test-output</code> directory. </p><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>The Saxon 6.5 jar should <span class="emphasis"><em>not</em></span> be in your
 102                   <code class="envar">CLASSPATH</code> when you generate the webhelp output. If you have any
 103                 problems, try running ant with an empty <code class="envar">CLASSPATH</code>.</p></div></li><li class="step" title="Step 6"><p>To process your own document, simply refer to this package
 104           from another <code class="filename">build.xml</code> in arbitrary location on
 105           your system:</p><ol type="a" class="substeps"><li class="step" title="Step 6.a"><p>Create a new <code class="filename">build.xml</code> file that
 106               defines the name of your source file, the desired output
 107               directory, and imports the <code class="filename">build.xml</code> from
 108               this package. For example: </p><pre class="programlisting">&lt;project&gt;
 109   &lt;property name="input-xml" value="<em class="replaceable"><code>path-to/yourfile.xml</code></em>"/&gt;
 110   &lt;property name="input-images-dirs" value="<em class="replaceable"><code>images/** figures/** graphics/**</code></em>"/&gt;
 111   &lt;property name="output-dir" value="<em class="replaceable"><code>path-to/desired-output-dir</code></em>"/&gt;
 112   &lt;import file="<em class="replaceable"><code>path-to/docbook-webhelp/</code></em>build.xml"/&gt;
 113 &lt;/project&gt;</pre></li><li class="step" title="Step 6.b"><p>From the directory containing your newly created
 114               <code class="filename">build.xml</code> file, type <code class="code">ant
 115               webhelp</code> to build your document.</p><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>The Saxon 6.5 jar should <span class="emphasis"><em>not</em></span> be in your
 116                     <code class="envar">CLASSPATH</code> when you generate the webhelp output. If you have any
 117                   problems, try running ant with an empty <code class="envar">CLASSPATH</code>.</p></div></li></ol></li></ol></div></div><script type="text/javascript" src="../common/main.js"></script><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch02s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></div><div><div id="leftnavigation" style="padding-top:3px; background-color:white;"><div id="tabs"><ul><li><a href="#treeDiv"><em>Contents</em></a></li><li><a href="#searchDiv"><em>Search</em></a></li></ul><div id="treeDiv"><img src="../common/images/loading.gif" alt="loading table of contents..." id="tocLoading" style="display:block;" /><div id="ulTreeDiv" style="display:none"><ul id="tree" class="filetree"><li><span class="file"><a href="ch01.html">Introduction</a></span></li><li><span class="file"><a href="ch02.html">Using the package</a></span><ul><li id="webhelp-currentid"><span class="file"><a href="ch02s01.html">Generating webhelp output</a></span></li><li><span class="file"><a href="ch02s02.html">Using and customizing the output</a></span><ul><li><span class="file"><a href="ch02s02.html#id36124136">Recommended Apache configurations</a></span></li></ul></li><li><span class="file"><a href="ch02s03.html">Building the indexer</a></span></li><li><span class="file"><a href="ch02s04.html">Adding support for other (non-CJKV) languages</a></span></li></ul></li><li><span class="file"><a href="ch03.html">Developer Docs</a></span><ul><li><span class="file"><a href="ch03s01.html">Design</a></span></li><li><span class="file"><a href="ch03s02.html">Search</a></span><ul><li><span class="file"><a href="ch03s02.html#id36124646">New Stemmers</a></span></li></ul></li></ul></li></ul></div></div><div id="searchDiv"><div id="search"><form onsubmit="Verifie(ditaSearch_Form);return false" name="ditaSearch_Form" class="searchForm" id="ditaSearch_Form"><fieldset class="searchFieldSet"><legend>Search</legend><center><input id="textToSearch" name="textToSearch" type="text" class="searchText" /> &nbsp; <input onclick="Verifie(ditaSearch_Form)" type="button" class="searchButton" value="Go" id="doSearch" /></center></fieldset></form></div><div id="searchResults"><center></center></div></div></div></div></div></body></html>