From c5e3ea759768fecdf4ab66870421f38673ab8bce Mon Sep 17 00:00:00 2001
From: David Cramer <david@thingbag.net>
Date: Sun, 6 May 2012 19:41:03 +0000
Subject: [PATCH] Webhelp: moving parameters into the standard location so they
 will be part of the parameter reference

---
 xsl/html/param.ent                            |  8 +++++
 xsl/html/param.xweb                           | 18 ++++++++++++
 xsl/params/base.dir.xml                       |  2 +-
 xsl/params/webhelp.autolabel.xml              |  6 ++--
 xsl/params/webhelp.base.dir.xml               |  8 +++--
 xsl/params/webhelp.common.dir.xml             |  4 +--
 xsl/params/webhelp.default.topic.xml          | 15 ++++++++--
 xsl/params/webhelp.include.search.tab.xml     |  4 +--
 xsl/params/webhelp.indexer.language.xml       | 29 +++++++++++++++++--
 xsl/params/webhelp.start.filename.xml         | 13 +++++++--
 xsl/params/webhelp.tree.cookie.id.xml         | 17 +++++++++--
 .../xsl/{webhelp.xsl => webhelp-common.xsl}   | 29 ++++++-------------
 12 files changed, 115 insertions(+), 38 deletions(-)
 rename xsl/webhelp/xsl/{webhelp.xsl => webhelp-common.xsl} (97%)

diff --git a/xsl/html/param.ent b/xsl/html/param.ent
index 18125e5f0..8434ea670 100644
--- a/xsl/html/param.ent
+++ b/xsl/html/param.ent
@@ -320,3 +320,11 @@
 <!ENTITY chunked.filename.prefix SYSTEM "../params/chunked.filename.prefix.xml">
 <!ENTITY html.script SYSTEM "../params/html.script.xml">
 <!ENTITY html.script.type SYSTEM "../params/html.script.type.xml">
+<!ENTITY webhelp.autolabel          SYSTEM "../params/webhelp.autolabel.xml">
+<!ENTITY webhelp.base.dir           SYSTEM "../params/webhelp.base.dir.xml">
+<!ENTITY webhelp.common.dir         SYSTEM "../params/webhelp.common.dir.xml">
+<!ENTITY webhelp.default.topic      SYSTEM "../params/webhelp.default.topic.xml">
+<!ENTITY webhelp.include.search.tab SYSTEM "../params/webhelp.include.search.tab.xml">
+<!ENTITY webhelp.indexer.language   SYSTEM "../params/webhelp.indexer.language.xml">
+<!ENTITY webhelp.start.filename     SYSTEM "../params/webhelp.start.filename.xml">
+<!ENTITY webhelp.tree.cookie.id     SYSTEM "../params/webhelp.tree.cookie.id.xml">
diff --git a/xsl/html/param.xweb b/xsl/html/param.xweb
index c591d37a3..c16c328b8 100644
--- a/xsl/html/param.xweb
+++ b/xsl/html/param.xweb
@@ -413,6 +413,16 @@ profiling of your document. For more information about profiling, see
 &eclipse.plugin.id;
 &eclipse.plugin.provider;
 </reference>
+<reference xml:id="webhelp"><title>WebHelp</title>
+&webhelp.autolabel;
+&webhelp.base.dir;
+&webhelp.common.dir;
+&webhelp.default.topic;
+&webhelp.include.search.tab;
+&webhelp.indexer.language;
+&webhelp.start.filename;
+&webhelp.tree.cookie.id;
+</reference>
 <reference xml:id="javahelp"><title>JavaHelp</title>
 &javahelp.encoding;
 </reference>
@@ -753,6 +763,14 @@ around all these parameters.</para>
 <src:fragref linkend="variablelist.as.table.frag"/>
 <src:fragref linkend="variablelist.term.break.after.frag"/>
 <src:fragref linkend="variablelist.term.separator.frag"/>
+<src:fragref linkend="webhelp.autolabel.frag"/>
+<src:fragref linkend="webhelp.base.dir.frag"/>
+<src:fragref linkend="webhelp.common.dir.frag"/>
+<src:fragref linkend="webhelp.default.topic.frag"/>
+<src:fragref linkend="webhelp.include.search.tab.frag"/>
+<src:fragref linkend="webhelp.indexer.language.frag"/>
+<src:fragref linkend="webhelp.start.filename.frag"/>
+<src:fragref linkend="webhelp.tree.cookie.id.frag"/>
 <src:fragref linkend="writing.mode.frag"/>
 <src:fragref linkend="xref.label-page.separator.frag"/>
 <src:fragref linkend="xref.label-title.separator.frag"/>
diff --git a/xsl/params/base.dir.xml b/xsl/params/base.dir.xml
index 1e8f3fcbf..4abf9c7c8 100644
--- a/xsl/params/base.dir.xml
+++ b/xsl/params/base.dir.xml
@@ -21,7 +21,7 @@
 
 <refsection><info><title>Description</title></info>
 
-<para>If specified, the <parameter>base.dir</parameter> identifies
+<para>If specified, the <parameter>base.dir</parameter> parameter identifies
 the output directory for chunks. (If not specified, the output directory
 is system dependent.)</para>
 
diff --git a/xsl/params/webhelp.autolabel.xml b/xsl/params/webhelp.autolabel.xml
index f96e257ac..de20701af 100644
--- a/xsl/params/webhelp.autolabel.xml
+++ b/xsl/params/webhelp.autolabel.xml
@@ -9,8 +9,8 @@
 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
 </refmeta>
 <refnamediv>
-<refname></refname>
-<refpurpose></refpurpose>
+<refname>webhelp.autolabel</refname>
+<refpurpose>Should tree-like ToC use autonumbering feature?</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -20,6 +20,6 @@
 </refsynopsisdiv>
 
 <refsection><info><title>Description</title></info>
-<para></para>
+<para>To include chapter and section numbers the table of contents pane, set this parameter to 1.</para>
 </refsection>
 </refentry>
diff --git a/xsl/params/webhelp.base.dir.xml b/xsl/params/webhelp.base.dir.xml
index 9cc14b885..1dcf6881b 100644
--- a/xsl/params/webhelp.base.dir.xml
+++ b/xsl/params/webhelp.base.dir.xml
@@ -10,7 +10,7 @@
 </refmeta>
 <refnamediv>
 <refname>webhelp.base.dir</refname>
-<refpurpose></refpurpose>
+<refpurpose>The base directory for webhelp output.</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -20,6 +20,10 @@
 </refsynopsisdiv>
 
 <refsection><info><title>Description</title></info>
-<para></para>
+<para>If specified, the <parameter>webhelp.base.dir</parameter>
+parameter identifies the output directory for webhelp. (If not
+specified, the output directory is system dependent.) By default, this
+parameter is set to <filename>docs</filename>.</para>
+
 </refsection>
 </refentry>
diff --git a/xsl/params/webhelp.common.dir.xml b/xsl/params/webhelp.common.dir.xml
index 448ee4dea..8d5267b76 100644
--- a/xsl/params/webhelp.common.dir.xml
+++ b/xsl/params/webhelp.common.dir.xml
@@ -10,7 +10,7 @@
 </refmeta>
 <refnamediv>
 <refname>webhelp.common.dir</refname>
-<refpurpose></refpurpose>
+<refpurpose>Path to the directory for the common webhelp resources (JavaScript, css, common images, etc).</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -20,6 +20,6 @@
 </refsynopsisdiv>
 
 <refsection><info><title>Description</title></info>
-<para></para>
+<para>By default, webhelp creates a common directory containing resources such as JavaScript files, css, common images, etc. In some cases you may prefer to store these files in a standard location on your site and point all webhelp documents to that location. You can use this parameter to control the urls written to these common resources. For example, you might set this parameter to <code>/common</code> and create a single common directory at the root of your web server.  </para>
 </refsection>
 </refentry>
diff --git a/xsl/params/webhelp.default.topic.xml b/xsl/params/webhelp.default.topic.xml
index 8df9ec66c..4dca60ed0 100644
--- a/xsl/params/webhelp.default.topic.xml
+++ b/xsl/params/webhelp.default.topic.xml
@@ -10,7 +10,7 @@
 </refmeta>
 <refnamediv>
 <refname>webhelp.default.topic</refname>
-<refpurpose></refpurpose>
+<refpurpose>The name of the file to which the start file in the webhelp base directory redirects</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -20,6 +20,17 @@
 </refsynopsisdiv>
 
 <refsection><info><title>Description</title></info>
-<para></para>
+<para>Currently webhelp creates a base directory and puts the output
+files in a <filename>content</filename> subdirectory. It creates a
+file in the base directory that redirects to a configured file in the
+<filename>content</filename> directory. The
+<parameter>webhelp.default.topic</parameter> parameter lets you
+configure the name of the file that is redirected to.
+<note>
+  <para>This parameter will be removed from a future version of
+  webhelp along with the <filename>content</filename>
+  directory.</para>
+</note>
+</para>
 </refsection>
 </refentry>
diff --git a/xsl/params/webhelp.include.search.tab.xml b/xsl/params/webhelp.include.search.tab.xml
index b880a8653..131f32d0d 100644
--- a/xsl/params/webhelp.include.search.tab.xml
+++ b/xsl/params/webhelp.include.search.tab.xml
@@ -10,7 +10,7 @@
 </refmeta>
 <refnamediv>
 <refname>webhelp.include.search.tab</refname>
-<refpurpose></refpurpose>
+<refpurpose>Should the webhelp output include a Search tab?</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -20,6 +20,6 @@
 </refsynopsisdiv>
 
 <refsection><info><title>Description</title></info>
-<para></para>
+<para>Set this parameter to 0 to suppress the search tab from webhelp output.</para>
 </refsection>
 </refentry>
diff --git a/xsl/params/webhelp.indexer.language.xml b/xsl/params/webhelp.indexer.language.xml
index f1ef191c3..34a5843d2 100644
--- a/xsl/params/webhelp.indexer.language.xml
+++ b/xsl/params/webhelp.indexer.language.xml
@@ -10,7 +10,7 @@
 </refmeta>
 <refnamediv>
 <refname>webhelp.indexer.language</refname>
-<refpurpose></refpurpose>
+<refpurpose>The language to use for creating the webhelp search index.</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -20,6 +20,31 @@
 </refsynopsisdiv>
 
 <refsection><info><title>Description</title></info>
-<para></para>
+<para>To support stemming in the client-side webhelp stemmer, you must provide the language code. By default, the following languages are supported:
+<itemizedlist>
+  <listitem>
+    <para><code>en</code>: English</para>
+  </listitem>
+  <listitem>
+    <para><code>de</code>: German</para>
+  </listitem>
+  <listitem>
+    <para><code>fr</code>: French</para>
+  </listitem>
+  <listitem>
+    <para><code>it</code>: Italian</para>
+  </listitem>
+  <listitem>
+    <para><code>cn</code>: Chinese</para>
+  </listitem>
+  <listitem>
+    <para><code>ja</code>: Japanese</para>
+  </listitem>
+  <listitem>
+    <para><code>ko</code>: Korean</para>
+  </listitem>
+</itemizedlist>
+See the webhelp documentation for information on adding support for additional languages.
+</para>
 </refsection>
 </refentry>
diff --git a/xsl/params/webhelp.start.filename.xml b/xsl/params/webhelp.start.filename.xml
index cf9ec65b8..2106de4c6 100644
--- a/xsl/params/webhelp.start.filename.xml
+++ b/xsl/params/webhelp.start.filename.xml
@@ -10,7 +10,7 @@
 </refmeta>
 <refnamediv>
 <refname>webhelp.start.filename</refname>
-<refpurpose></refpurpose>
+<refpurpose>The name of the start file in the webhelp base directory.</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -20,6 +20,15 @@
 </refsynopsisdiv>
 
 <refsection><info><title>Description</title></info>
-<para></para>
+<para>Currently webhelp creates a base directory and puts the output
+files in a <filename>content</filename> subdirectory. It creates a
+file in the base directory that redirects to a configured file in the
+<filename>content</filename> directory. The <parameter>webhelp.start.filename</parameter> parameter lets you configure the name of the redirect file.
+<note>
+  <para>This parameter will be removed from a future version of
+  webhelp along with the <filename>content</filename>
+  directory.</para>
+</note>
+</para>
 </refsection>
 </refentry>
diff --git a/xsl/params/webhelp.tree.cookie.id.xml b/xsl/params/webhelp.tree.cookie.id.xml
index d6a2c688e..8f790be5d 100644
--- a/xsl/params/webhelp.tree.cookie.id.xml
+++ b/xsl/params/webhelp.tree.cookie.id.xml
@@ -10,7 +10,7 @@
 </refmeta>
 <refnamediv>
 <refname>webhelp.tree.cookie.id</refname>
-<refpurpose></refpurpose>
+<refpurpose>Controls how the cookie that stores the webhelp toc state is named.</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -20,6 +20,19 @@
 </refsynopsisdiv>
 
 <refsection><info><title>Description</title></info>
-<para></para>
+<para>The webhelp output does not use a frameset. Instead, the table of contents is a div on each page. To preserve the state of the table of contents as the user navigates from page to page, webhelp stores the state in a cookie and reads that cookie when you get to the next page. If you've published several webhelp documents on the same domain, it is important that each cookie have a unique id. In lieu of calling on a GUID generator, by default this parameter is just set to the number of nodes in the document on the assumption that it is unlikely that you will have more than one document with the exact number of nodes. A more optimal solution would be for the user to pass in some unique, stable identifier from the build system to use as the webhelp cookie id. For example, if you have safeguards in place to ensure that the xml:id of the root element of each document will be unique on your site, then you could set webhelptree.cookie.id as follows:
+<programlisting><![CDATA[
+  <xsl:param name="webhelp.tree.cookie.id">
+    <xsl:choose>
+      <xsl:when test="/*/@xml:id">
+	<xsl:value-of select="concat('treeview-',/*/@xml:id)"/>
+      </xsl:when>
+      <xsl:otherwise>
+	<xsl:value-of select="concat( 'treeview-', count(//node()) )"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:param>]]>
+  </programlisting>
+ </para>
 </refsection>
 </refentry>
diff --git a/xsl/webhelp/xsl/webhelp.xsl b/xsl/webhelp/xsl/webhelp-common.xsl
similarity index 97%
rename from xsl/webhelp/xsl/webhelp.xsl
rename to xsl/webhelp/xsl/webhelp-common.xsl
index 5dd41f0bb..6cc7273a0 100644
--- a/xsl/webhelp/xsl/webhelp.xsl
+++ b/xsl/webhelp/xsl/webhelp-common.xsl
@@ -6,6 +6,15 @@
         version="1.0" xmlns="http://www.w3.org/1999/xhtml"
 	exclude-result-prefixes="exsl ng db">
 
+<!-- ********************************************************************
+     $Id$
+     ******************************************************************** 
+
+     This file is part customization layer on top of the XSL DocBook
+     Stylesheet distribution that generates webhelp output.
+
+     ******************************************************************** -->
+
     <xsl:import href="../../xhtml/chunk.xsl"/>
 
     <xsl:output
@@ -24,26 +33,6 @@
       <xsl:call-template name="get.doc.title"/>
     </xsl:param>
 
-    <!-- webhelp-specific params! -->
-    <!-- To be added to normal params file someday -->
-    <xsl:param name="webhelp.include.search.tab">true</xsl:param>
-    <xsl:param name="webhelp.start.filename">index.html</xsl:param>
-    <xsl:param name="webhelp.base.dir">docs</xsl:param>
-    <!-- webhelp.common.dir includes the files including jquery, css files
-	 which are required for general functionality of webhelp -->
-    <xsl:param name="webhelp.common.dir">../common/</xsl:param>
-    <!-- webhelp.tree.cookie.id preserves the TOC tree. 
-	i.e. opened tree/sub-tree nodes and closed tree nodes. 
-	Needed for jquery.treeview plugin -->
-    <xsl:param name="webhelp.tree.cookie.id" select="concat( 'treeview-', count(//node()) )"/>
-    <!-- Specify the language of your docbook document. 
-	This is needed for stemming support and to filter the subtle differences in the languages 
-	'en' (english) is the default. Refer the NOTE: on stemmers given below for more info. -->
-    <xsl:param name="webhelp.indexer.language">en</xsl:param>
-    <xsl:param name="webhelp.default.topic">index.html</xsl:param>
-    <xsl:param name="webhelp.autolabel">0</xsl:param>
-    <!-- webhelp-specific params! -->
-
     <!-- Set some reasonable defaults for webhelp output -->
     <xsl:param name="chunker.output.indent">yes</xsl:param>
     <xsl:param name="navig.showtitles">0</xsl:param>
-- 
2.40.0