OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Webhelp adventures: the gory details


Hi, all.

In my excessively long "Adventures in Webhelp" note, I offered to provide
some of the customizations I did to interested parties. I have attached
three stylesheets and one Perl script. (This note probably won't make much
sense if you haven't read that prior one, since I refer to issues noted there.)

I have attached the stylesheet I use to generate a single, generic sidebar
TOC into a file as a preprocessing step. This is not dependent on any of
the webhelp stylesheets, though it consists of the TOC-building template
from webhelp. The main stylesheet is the one that contains the customizations
I made for generating the chunked HTML. This is where I refactored some of
the templates, parameterized some of the customization hooks that weren't
parameterized, and otherwise overrode a bunch of webhelp-common.xsl.
The third simply contains my modified "object.id" template, which is imported
into the other two.

The Perl script is run as a preliminary step for doing search indexing.
It has two main jobs: fixing that unclosed meta tag (Content-Type) (which
is what I wrote it for originally), and adding "webhelp-currentid" at the
right place in each file's copy of the sidebar TOC.

Note that these are NOT exactly the version we use, since I have
stripped out some non-webhelp-related customizations, and some "corporate"
branding things. (The only one that's substantially different is the HTML chunking
XSL. The rest were so small and generic that there wasn't really
much to remove. But all the "webhelp"-related stuff is here.)

I've also attached a screen shot that shows what our webhelp looks like.
The content is the README from the DocBook webhelp itself.

Here is the basic build sequence we use. We have a TON of Ant scripts,
and I'm not going to try and provide them, since they are highly specific
to our environment, and not easily "genericized". I'll be happy to answer
any questions about what the steps do, but most of this is straightforward
if you've got webhelp already building.

A couple of things to note:

  * The <book> documents we wrap into <set>s are all stand-alone, so we are
    NOT doing o-linking between them. There are no passes
    to generate target databases.

  * We are also NOT profiling.

This is what we do for each of our "helpset" documents (XML <set> files
that xinclude one or more <book> documents):

1. Delete any old output tree, and create a new output tree. This will
   be zipped up for installation with the product. (This structure
   is basically the webhelp template, with some additional directories
   for our product images.)

2. Copy our CSS file into the expected location in the output tree.

3. Copy our doc-related graphics into the output tree. This includes our
   content graphics, admonition icons, and HTML-specific icons.

4. Copy the parts we are using from the DocBook Webhelp template
   into the output tree. We skip a lot of the "common" images (because
   we replace them with our own in the next step), and some of the JS library
   images (like callouts), which we just don't use or need.

5. Copy our modifications to the DocBook Webhelp template
   into the output tree. This is mostly images, but we also have a
   modified version of "main.js" (we commented out a block of code
   as a solution to a problem with within-page links, and we changed
   some of the hard-coded colors. No other changes were made).

6. Generate the generic sidebar TOC using XSLTproc and "mt-webhelptoc.xsl".

7. Generate the webhelp HTML files using XSLTproc and "mt-wehbelp.xsl".
   This step splices a copy of the generic sidebar TOC into each file.

8. Generate the search indices. This actually is three steps:

   First, we run the "post-process-html" Perl script on the HTML files.
   This fixes an issue with an unclosed "meta" element and adds the
   "webhelp-currentid" to the right place in the generic sidebar TOC for
   the file being processed.

   Second, we run the "IndexerMain" class from the DocBook stylesheets.

   Third, we delete the temp files generated during search indexing but
   not used in running searches.

The output tree is then zipped up for installation with the product.

Again, I do not suggest that the customizations I have made are in any
way suitable for general-purpose use, but perhaps they may inform some
discussion for possible refinements. I hope someone finds this at least
interesting. Feel free to contact me directly if you want

Thanks for hanging with me this long!

-- Mary
<?xml version='1.0'?>
<xsl:stylesheet
       xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
       xmlns:exsl="http://exslt.org/common";
       xmlns:ng="http://docbook.org/docbook-ng";
       xmlns:db="http://docbook.org/ns/docbook";
       version="1.0" xmlns="http://www.w3.org/1999/xhtml";
              exclude-result-prefixes="exsl ng db">

  <!-- This stylesheet overrides some of the webhelp-common templates.
       It will require version 1.78.1 or higher of the DocBook XSL to
       work correctly.
  -->

  <!-- This is used simply to make the project and product stylesheets
       independently relocatable. This stylesheet needs to import the
       DocBook XSL stylesheet for webhelp, so the result should be
       something like this:
       <xsl:import href="c:/doc-stuff/docbook_xsl/docbook-xsl-1.78.1/webhelp/xsl/webhelp.xsl"/>
       -->
  <xsl:import href="@REDIRECT-DIR@/webhelp/xsl/webhelp.xsl"/>

  <!-- Import the shared project-specific stylesheet (used by
       mt-webhelptoc.xsl and mt-webhelp.xsl.) -->
  <xsl:import href="mt-webhelp-ids.xsl"/>

  <!-- /////////////// Stylesheet parameters //////////////////////// -->

  <xsl:param name="product.name" select="'PRODUCT'"/> 

  <!-- HTML chunking values; override values in Docbook's webhelp-common.xsl -->
  <xsl:param name="chunk.first.sections" select="0"/>
  <xsl:param name="chunk.section.depth" select="1"/>

  <!-- Parameters to pass down the to underlying stylesheet
       (sidebar.tocfile.name provided via stringparam) -->
  <xsl:param name="webhelp.stylesheet"   select="'our-webhelp.css'"/> 
  <xsl:param name="sidebar.tocfile.name" select="''"/>

  <!-- This is used as the "tab title" for the every webhelp page; ideally
       this would be pulled from the "set" title in the document, but
       this at least prevents the tab title from changing with each page
       that gets loaded.-->
  <xsl:param name="webhelp.title" select="'Webhelp README'"/>
  

  <!-- HTML formatting: Put navigation links and titles on pages? --> 
  <xsl:param name="suppress.navigation">0</xsl:param>
  <xsl:param name="suppress.header.navigation.in.webhelp">1</xsl:param>
  <xsl:param name="suppress.footer.navigation.in.webhelp">1</xsl:param>
  <xsl:param name="navig.showtitles">1</xsl:param>
  <xsl:param name="navig.graphics" select="1"/>
  <xsl:param name="navig.graphics.path">nav-images/</xsl:param>
  <xsl:param name="navig.graphics.extension" select="'.png'"/>

  <!-- Include the "sidebar" toggle button in the navbar? -->
  <xsl:param name="include.sidebar.toggle.in.navbar">1</xsl:param>
  
  <!--Do NOT use the IDs as html filenames-->
  <xsl:param name="use.id.as.filename" select="0"></xsl:param>


  <!-- /////////////// Stylesheet templates //////////////////////// -->

  <!-- ////// Navigation components ////// -->

  <!-- Builds a custom navigation bar, can be used in the stationary
       header, or in the nav-header/nav-footers like in the "pure"
       HTML format (in the "content" div)-->
  <xsl:template name="write.our.navbar">
    <xsl:param name="prev"/>
    <xsl:param name="next"/>
    <xsl:param name="nav.context"/>

    <xsl:variable name="home" select="/*[1]"/>
    <xsl:variable name="make-navtable"
                  select="($prev and $navig.showtitles != 0)
                           or (generate-id($home) != generate-id(.)
                               or $nav.context = 'toc')
                           or ($chunk.tocs.and.lots != 0
                               and $nav.context != 'toc')
                           or ($next and $navig.showtitles != 0)"/>

    <xsl:variable name="include-sidebar"
                  select="($include.sidebar.toggle.in.navbar != 0)"/>

    <xsl:if test="$make-navtable">
      <table width="100%" border="0" align="right" cellpadding="3"
             cellspacing="0" summary="Navigation bar">
        <tbody>
        <tr valign="bottom">

          <xsl:if test="$include-sidebar">
            <!-- This is stolen from the default webhelp XSL -->
            <td width="1%" height="29px" align="left" valign="bottom">
              <div style="width:265px; font-size: xx-small; color:#000;">
              <a id="sidebarToggle2" href="#" onclick="myLayout.toggle('west')"
                 class="pointLeft" tabindex="5" title="Show/hide sidebar">
                <img src="common/images/sidebar.png"
                     alt="Show/hide sidebar"/>
              </a>
              <xsl:text disable-output-escaping="yes"><![CDATA[&nbsp;]]>Sidebar</xsl:text>
              </div>
            </td>
          </xsl:if>

          <td width="2%" valign="bottom">
            <xsl:text disable-output-escaping="yes"><![CDATA[&nbsp;]]></xsl:text>
          </td>

          <td width="1%" align="left" valign="bottom">
            <xsl:if test="count($prev)>0">
              <a accesskey="p">
                <xsl:attribute name="href">
                  <xsl:call-template name="href.target">
                    <xsl:with-param name="object" select="$prev"/>
                  </xsl:call-template>
                </xsl:attribute>
                <xsl:call-template name="navig.content">
                  <xsl:with-param name="direction" select="'prev'"/>
                </xsl:call-template>
              </a>
            </xsl:if>
            <xsl:text> </xsl:text>
          </td>

          <td align="left" valign="bottom"
              style="font-size: xx-small; color:#000;">
            <xsl:if test="$navig.showtitles != 0">
              <xsl:apply-templates select="$prev" mode="object.title.markup"/>
            </xsl:if>
            <xsl:text> </xsl:text>
          </td>

          <td align="right" valign="bottom" style="font-size: xx-small; color:#000;">
            <xsl:if test="$navig.showtitles != 0">
              <xsl:apply-templates select="$next" mode="object.title.markup"/>
            </xsl:if>
            <xsl:text> </xsl:text>
          </td>

          <td width="1%" align="right" valign="bottom">
            <xsl:if test="count($next)>0">
              <a accesskey="n">
                <xsl:attribute name="href">
                  <xsl:call-template name="href.target">
                    <xsl:with-param name="object" select="$next"/>
                  </xsl:call-template>
                </xsl:attribute>
                <xsl:call-template name="navig.content">
                  <xsl:with-param name="direction" select="'next'"/>
                </xsl:call-template>
              </a>
            </xsl:if>
            <xsl:text> </xsl:text>
          </td>

          <td width="2%" valign="bottom">
            <xsl:text disable-output-escaping="yes"><![CDATA[&nbsp;]]></xsl:text>
          </td>
        </tr>
        </tbody>
      </table>
    </xsl:if>
  </xsl:template>
  <!-- ///// End navigation ////// -->  
  


  <!-- ////// Overrides of templates in webhelp-common.xsl /////////// -->

  <xsl:template name="chunk-element-content">
    <xsl:param name="prev"/>
    <xsl:param name="next"/>
    <xsl:param name="nav.context"/>
    <xsl:param name="content">
      <xsl:apply-imports/>
    </xsl:param>

    <xsl:call-template name="user.preroot"/>

    <html>
      <xsl:call-template name="html.head">
        <xsl:with-param name="prev" select="$prev"/>
        <xsl:with-param name="next" select="$next"/>
      </xsl:call-template>

      <body>
        <noscript>
          <div id="noscript">
            <xsl:call-template name="gentext.template">
              <xsl:with-param name="name" select="'txt_browser_not_supported'"/>
              <xsl:with-param name="context" select="'webhelp'"/>
            </xsl:call-template>
          </div>
        </noscript>

        <xsl:call-template name="body.attributes"/>

        <!-- This generates the stock webhelp navbar in the header, with the
             sidebar toggle and so forth -->
        <xsl:call-template name="user.header.navigation">
          <xsl:with-param name="prev" select="$prev"/>
          <xsl:with-param name="next" select="$next"/>
          <xsl:with-param name="nav.context" select="$nav.context"/>
        </xsl:call-template>

        <div id="content">
          <!-- The original template didn't provide parameters to this
               invocation, which is why we overrode. This inserts the
               "our-navbar" header at the top of the content section.
               We ended up not using this template, but our original
               designed called for a nav bar at the top and bottom of
               each page (that's what we had in the CHM files) -->
          <xsl:call-template name="user.header.content">
            <xsl:with-param name="prev" select="$prev"/>
            <xsl:with-param name="next" select="$next"/>
            <xsl:with-param name="nav.context" select="$nav.context"/>
          </xsl:call-template>

          <xsl:copy-of select="$content"/>

          <xsl:call-template name="user.footer.content"/>
          <xsl:call-template name="footer.navigation">
            <xsl:with-param name="prev" select="$prev"/>
            <xsl:with-param name="next" select="$next"/>
            <xsl:with-param name="nav.context" select="$nav.context"/>
          </xsl:call-template>

          <xsl:call-template name="user.webhelp.content.footer"/>
        </div>

        <xsl:call-template name="user.footer.navigation"/>
      </body>
    </html>
    <xsl:value-of select="$chunk.append"/>
  </xsl:template>


  <!-- HTML <head> section customizations -->  
  <!-- This overrides the "user.head.content" template found in
       webhelp-common.xsl. We only needed to override parts of it, but
       it was one enormous template, so I also refactored it into several
       smaller templates that could be more selectively overridden. -->
  <xsl:template name="user.head.content">
    <xsl:param name="title">
      <xsl:apply-templates select="." mode="object.title.markup.textonly"/>
    </xsl:param>
    <meta name="Section-title" content="{$title}"/>   

    <!-- TODO: Move this to another template for Webhelp localization -->
    <script type="text/javascript">
  //The id for tree cookie
  var treeCookieId = "<xsl:value-of select="$webhelp.tree.cookie.id"/>";
  var language = "<xsl:value-of select="$webhelp.indexer.language"/>";
  var w = new Object();
  //Localization
  txt_filesfound = '<xsl:call-template name="gentext.template">
    <xsl:with-param name="name" select="'txt_filesfound'"/>
    <xsl:with-param name="context" select="'webhelp'"/>
  </xsl:call-template>';
  txt_enter_at_least_1_char = "<xsl:call-template name="gentext.template">
    <xsl:with-param name="name" select="'txt_enter_at_least_1_char'"/>
    <xsl:with-param name="context" select="'webhelp'"/>
  </xsl:call-template>";
  txt_browser_not_supported = "<xsl:call-template name="gentext.template">
    <xsl:with-param name="name" select="'txt_browser_not_supported'"/>
    <xsl:with-param name="context" select="'webhelp'"/>
  </xsl:call-template>";
  txt_please_wait = "<xsl:call-template name="gentext.template">
    <xsl:with-param name="name" select="'txt_please_wait'"/>
    <xsl:with-param name="context" select="'webhelp'"/>
  </xsl:call-template>";
  txt_results_for = "<xsl:call-template name="gentext.template">
    <xsl:with-param name="name" select="'txt_results_for'"/>
    <xsl:with-param name="context" select="'webhelp'"/>
  </xsl:call-template>";
    </script>

    <!-- Add external JS and CSS files to the "head" HTML header. -->
    <xsl:call-template name="webhelp.add.js.css.to.head"/>

    <!-- Add the project stylehsheet(s) to the "head" HTML header. -->
    <xsl:call-template name="webhelp.add.project.css.to.head"/>

    <!-- Add any CSS overrides for above CSS files here -->
<!-- Prefer adding overrides to project css, since that's the "last one in"
    <xsl:call-template name="webhelp.add.css.overrides.to.head"/>
-->

    <xsl:comment><xsl:text>[if IE]>
&lt;link rel="stylesheet" type="text/css" href="../common/css/ie.css"/>
&lt;![endif]</xsl:text></xsl:comment>

    <!-- Add JSQuery support -->
    <xsl:call-template name="webhelp.add.jquery.support.to.head"/>

    <!-- Add scripts/CSS stylesheets for Search tab (if used) -->
    <xsl:call-template name="webhelp.add.search.js.to.head"/>

    <xsl:call-template name="user.webhelp.head.content"/>
  </xsl:template>

  <!-- =====================================================================
       These "webhelp.add.*" templates were broken out of the original,
       monolithic "user.head.content" template provided with the stylesheets.
  -->

  <!-- Adds external JS and CSS files to the "head" HTML header.
       Order is important between the in-html-file CSS and the
       linked CSS files. 
  -->
  <xsl:template name="webhelp.add.js.css.to.head">
    <link rel="shortcut icon" href="favicon.ico" type="image/x-icon"/>
    <link rel="stylesheet" type="text/css"
          href="{$webhelp.common.dir}css/positioning.css"/>
    <link rel="stylesheet" type="text/css"
          href="{$webhelp.common.dir}jquery/theme-redmond/jquery-ui-1.8.2.custom.css"/>
    <link rel="stylesheet" type="text/css"
          href="{$webhelp.common.dir}jquery/treeview/jquery.treeview.css"/>
  </xsl:template>

  <!-- This lets us put the project-specific CSS in last, after the
       provided CSS files, rather than putting the project CSS first,
       as in the stock stylesheets.
  -->
  <xsl:template name="webhelp.add.project.css.to.head">
    <xsl:if test="$webhelp.stylesheet != ''">
      <xsl:call-template name="output.html.stylesheets">
        <xsl:with-param name="stylesheets"
                        select="normalize-space($webhelp.stylesheet)"/>
      </xsl:call-template>
    </xsl:if>
  </xsl:template>


  <!-- Writes CSS elements directly into the HTML file to override any
       of the styling done by external CSS files.
  
      NOTE: These overrides work so that our project-specific CSS stylesheet
      is the last one in, after those provided by the DocBook webhelp template,
      so all of this has been simply moved to that project's CSS file.
      There is no need to hardcode such CSS stuff into each HTML page!

      In other words, using this template is probably unnecessary.
  -->
  <xsl:template name="webhelp.add.css.overrides.to.head">
    <style type="text/css">
#noscript{
  font-weight:bold;
  background-color: #ffdb4a;
  font-weight: bold;
  height: 25spx;
  z-index: 3000;
  top:0px;
  width:100%;
  position: relative;
  border-bottom: solid 5px black;
  text-align:center;
  color: #000;
}

input {
  margin-bottom: 5px;
  margin-top: 2px;
}

.folder {
  display: block;
  height: 22px;
  padding-left: 20px;
  background: transparent url(<xsl:value-of select="$webhelp.common.dir"/>jquery/treeview/images/folder.gif) 0 0px no-repeat;
}

span.contentsTab {
  padding-left: 20px;
  background: url(<xsl:value-of select="$webhelp.common.dir"/>images/toc-icon.png) no-repeat 0 center;
}

span.searchTab {
  padding-left: 20px;
  background: url(<xsl:value-of select="$webhelp.common.dir"/>images/search-icon.png) no-repeat 0 center;
}

/* Overide jquery treeview's defaults for ul. */
.treeview ul {
  background-color: transparent;
  margin-top: 4px;
}    

#webhelp-currentid {
  background-color: #D8D8D8 !important;
}

.treeview .hover {
  color: black;
}

.filetree li span a {
  text-decoration: none;
  font-size: 12px;
  color: #517291; 
}

/* Override jquery-ui's default css customizations.
   These are supposed to take precedence over those.*/
.ui-widget-content {
  border: 0px; 
  background: none; 
  color: none;     
}

.ui-widget-header {
  color: #e9e8e9;
  border-left: 1px solid #e5e5e5;
  border-right: 1px solid #e5e5e5;
  border-bottom: 1px solid #bbc4c5;
  border-top: 4px solid #e5e5e5;
  border: medium none;
  background: #F4F4F4; /* old browsers */
  background: -moz-linear-gradient(top, #F4F4F4 0%, #E6E4E5 100%); /* firefox */
  background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#F4F4F4), color-stop(100%,#E6E4E5)); /* webkit */    
  font-weight: none;
}

.ui-widget-header a {
  color: none;
}
.ui-state-default, .ui-widget-content .ui-state-default, .ui-widget-header .ui-state-default { 
  border: none;
  background: none;
  font-weight: none;
  color: none;
}

.ui-state-default a, .ui-state-default a:link, .ui-state-default a:visited {
  color: black;
  text-decoration: none; 
}

.ui-state-hover, .ui-widget-content .ui-state-hover, .ui-widget-header .ui-state-hover, .ui-state-focus, .ui-widget-content .ui-state-focus, .ui-widget-header .ui-state-focus {
  border: none;
  background: none;
  font-weight: none;
  color: none;
}

.ui-state-active, .ui-widget-content .ui-state-active, .ui-widget-header .ui-state-active {
  border: none;
  background: none;
  font-weight: none;
  color: none;
}

.ui-state-active a, .ui-state-active a:link, .ui-state-active a:visited { 
  color: black; text-decoration: none;   
  background: #C6C6C6; /* old browsers */
  background: -moz-linear-gradient(top, #C6C6C6 0%, #D8D8D8 100%); /* firefox */
  background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#C6C6C6), color-stop(100%,#D8D8D8)); /* webkit */
  -webkit-border-radius:15px;
  -moz-border-radius:10px;
  border: 1px solid #f1f1f1;
}    

.ui-corner-all {
  border-radius: 0 0 0 0;
}

.ui-tabs {
  padding: .2em;
}

.ui-tabs .ui-tabs-nav li {
  top: 0px;
  margin: -2px 0 1px;
  text-transform: uppercase;
  font-size: 10.5px;
}

.ui-tabs .ui-tabs-nav li a {
  padding: .25em 2em .25em 1em;
  margin: .5em;
  text-shadow: 0 1px 0 rgba(255,255,255,.5);
}

/**
 *  JQuery UI Layout: Basic Layout Theme
 * 
 *  This theme uses the default layout class-names for all classes
 *  Add any 'custom class-names', from options: paneClass, resizerClass,
 * togglerClass
 */

.ui-layout-pane { /* all 'panes' */ 
  background: #FFF; 
  border: 1px solid #BBB; 
  padding: 05x; 
  overflow: auto;
} 
        
.ui-layout-resizer { /* all 'resizer-bars' */ 
  background: #DDD; 
  top:100px
} 

.ui-layout-toggler { /* all 'toggler-buttons' */ 
  background: #AAA; 
} 
    </style>
  </xsl:template>


  <!-- Adds the various JQuery libraries to the HTML head element -->
  <xsl:template name="webhelp.add.jquery.support.to.head">
    <xsl:comment><xsl:text>[if IE]>
      &lt;link rel="stylesheet" type="text/css" href="../common/css/ie.css"/>
      &lt;![endif]</xsl:text></xsl:comment>

    <!-- browserDetect is an Oxygen addition to warn the user if they're
         using chrome from the file system. This breaks the Oxygen search
         highlighting.
    -->
    <script type="text/javascript" src="{$webhelp.common.dir}browserDetect.js">
      <xsl:comment> </xsl:comment>
    </script>
    <script type="text/javascript" src="{$webhelp.common.dir}jquery/jquery-1.7.2.min.js">
      <xsl:comment> </xsl:comment>
    </script>
    <script type="text/javascript" src="{$webhelp.common.dir}jquery/jquery.ui.all.js">
      <xsl:comment> </xsl:comment>
    </script>
    <script type="text/javascript" src="{$webhelp.common.dir}jquery/jquery.cookie.js">
      <xsl:comment> </xsl:comment>
    </script>
    <script type="text/javascript" src="{$webhelp.common.dir}jquery/treeview/jquery.treeview.min.js">
      <xsl:comment> </xsl:comment>
    </script>
     <script type="text/javascript" src="{$webhelp.common.dir}jquery/layout/jquery.layout.js">
      <xsl:comment> </xsl:comment>
    </script>
  </xsl:template>

  <!-- Adds scripts/CSS stylesheets for Search tab, if used. -->
  <xsl:template name="webhelp.add.search.js.to.head">
    <xsl:if test="$webhelp.include.search.tab != '0'">
      <script type="text/javascript" src="search/l10n.js">
        <xsl:comment/>
      </script>
      <script type="text/javascript" src="search/htmlFileInfoList.js">
        <xsl:comment> </xsl:comment>
      </script>
      <script type="text/javascript" src="search/nwSearchFnt.js">
        <xsl:comment> </xsl:comment>
      </script>

      <script type="text/javascript" src="{concat('search/stemmers/',$webhelp.indexer.language,'_stemmer.js')}">
        <xsl:comment> </xsl:comment>
      </script>
      <script type="text/javascript" src="search/index-1.js">
        <xsl:comment> </xsl:comment>
      </script>
      <script type="text/javascript" src="search/index-2.js">
        <xsl:comment> </xsl:comment>
      </script>
      <script type="text/javascript" src="search/index-3.js">
        <xsl:comment> </xsl:comment>
      </script>
    </xsl:if>
  </xsl:template>


  <!-- This customized version of the webhelpheader puts our logos
       (without a "title" into the header (as "home" buttons), and includes
       our customized nav bar. We aren't using "home" or "up". -->
  <xsl:template name="webhelpheader">
    <xsl:param name="prev"/>
    <xsl:param name="next"/>
    <xsl:param name="nav.context"/>

<!--
    <xsl:variable name="home" select="/*[1]"/>
    <xsl:variable name="up" select="parent::*"/>
-->

    <div id="header">
      <table width="100%" border="0" cellspacing="0" cellpadding="0">
      <tbody>
        <tr>
          <td width="50%" height="60px" align="left" valign="bottom">
            <xsl:call-template name="webhelpheader.logo"/>
          </td>
          <td align="center" valign="bottom">
            <xsl:call-template name="webhelpheader.helplogo"/>
          </td>
        <tr>
        </tr>
          <td colspan="2">
            <xsl:call-template name="write.our.navbar">
              <xsl:with-param name="prev" select="$prev"/>
              <xsl:with-param name="next" select="$next"/>
              <xsl:with-param name="nav.context" select="$nav.context"/>
            </xsl:call-template>
          </td>
        </tr>
      </tbody>
      </table>
    </div>
  </xsl:template>


  <!-- We had to override the "logo" because the style is embedded
       in the generated HTML, and we needed to alter it slightly -->
  <xsl:template name="webhelpheader.logo">
    <a href="index.html">
      <img src='{$webhelp.common.dir}images/logo.png'
           alt="{$product.name} Documentation"
           height="45"
           style='margin-left: 15px;' />
    </a>
  </xsl:template>

  <!-- Added this to use a logo rather than a text title for the doc -->
  <xsl:template name="webhelpheader.helplogo">
    <a href="index.html">
      <img src='{$webhelp.common.dir}images/product_help.png'
           alt="{$product.name} Help"
           height="45"/>
    </a>
  </xsl:template>

  <!-- We override the "user.head.title" template so that only the
       a specific "webhelp title" (that of the "set" document for the various
       helpsets) is used as the title of the HTML page, so what shows up
       in the browser tab stays constant, rather than updating with each
       page's "content title" (not useful with deep subsections).
  -->
  <xsl:template name="user.head.title">
    <title>
      <xsl:copy-of select="$webhelp.title"/> 
    </title>
  </xsl:template>


  <!-- We override the "webhelptoc" template mainly to change a couple
       of lines. 

       NOTE: This template doesn't actually make the Webhelp TOC; it writes
       the "sidebar" div that holds the TOC and Search tabs. The TOC is
       actually generated by another template.

       The stock version of this template calls another template that
       generates the sidebar TOC for each page (creating the "tree" list).
       In other words, the TOC is recomputed for every HTML page written.
       We replace that with a call to read in the content of a previously
       generated file, avoiding the re-generation of this TOC for every
       HTML file we write. This HTML file is written by the mt-webhelptoc.xsl
       stylesheet, which must be invoked before this one.
  -->
  <xsl:template name="webhelptoc">
    <xsl:param name="currentid"/>
    <xsl:choose>
      <xsl:when test="$rootid != ''">

        <xsl:variable name="title">
          <xsl:if test="$webhelp.autolabel=1">
            <xsl:variable name="label.markup">
              <xsl:apply-templates select="key('id',$rootid)"
                                   mode="label.markup"/>
            </xsl:variable>
            <xsl:if test="normalize-space($label.markup)">
              <xsl:value-of select="concat($label.markup,$autotoc.label.separator)"/>
            </xsl:if>
          </xsl:if>
          <xsl:apply-templates select="key('id',$rootid)"
                               mode="titleabbrev.markup"/>
        </xsl:variable>

        <xsl:variable name="href">
          <xsl:choose>
            <xsl:when test="$manifest.in.base.dir != 0">
              <xsl:call-template name="href.target">
                <xsl:with-param name="object" select="key('id',$rootid)"/>
              </xsl:call-template>
            </xsl:when>
            <xsl:otherwise>
              <xsl:call-template name="href.target.with.base.dir">
                <xsl:with-param name="object" select="key('id',$rootid)"/>
              </xsl:call-template>
            </xsl:otherwise>
          </xsl:choose>
        </xsl:variable>
      </xsl:when>

      <xsl:otherwise>
        <xsl:variable name="title">
          <xsl:if test="$webhelp.autolabel=1">
            <xsl:variable name="label.markup">
              <xsl:apply-templates select="/*" mode="label.markup"/>
            </xsl:variable>
            <xsl:if test="normalize-space($label.markup)">
              <xsl:value-of select="concat($label.markup,$autotoc.label.separator)"/>
            </xsl:if>
          </xsl:if>
          <xsl:apply-templates select="/*" mode="titleabbrev.markup"/>
        </xsl:variable>

        <xsl:variable name="href">
          <xsl:choose>
            <xsl:when test="$manifest.in.base.dir != 0">
              <xsl:call-template name="href.target">
                <xsl:with-param name="object" select="/"/>
              </xsl:call-template>
            </xsl:when>
            <xsl:otherwise>
              <xsl:call-template name="href.target.with.base.dir">
                <xsl:with-param name="object" select="/"/>
              </xsl:call-template>
            </xsl:otherwise>
          </xsl:choose>
        </xsl:variable>

        <!--Note: #sidebar ID is used for showing and hiding the side bar -->
        <div id="sidebar">
          <div id="leftnavigation" style="padding-top:3px;">
            <div id="tabs">
              <ul>
                <li>
                  <a href="#treeDiv" style="outline:0;" tabindex="1">
                    <span class="contentsTab">
                      <xsl:call-template name="gentext.template">
                        <xsl:with-param name="name" select="'TableofContents'"/>
                        <xsl:with-param name="context" select="'webhelp'"/>
                      </xsl:call-template>
                    </span>
                  </a>
                </li>
                <xsl:if test="$webhelp.include.search.tab != '0'">
                  <li>
                    <a href="#searchDiv"
                       style="outline:0;" tabindex="1" onclick="doSearch()">
                      <span class="searchTab">
                        <xsl:call-template name="gentext.template">
                          <xsl:with-param name="name" select="'Search'"/>
                          <xsl:with-param name="context" select="'webhelp'"/>
                        </xsl:call-template>
                      </span>
                    </a>
                  </li>
                </xsl:if>
                <xsl:call-template name="user.webhelp.tabs.title"/>
              </ul>

              <div id="treeDiv">
                <img src="{$webhelp.common.dir}images/loading.gif"
                     alt="loading table of contents..."
                     id="tocLoading" style="display:block;"/>
                <div id="ulTreeDiv" style="display:none">

                  <!-- Instead of generating the sidebar TOC for each page,
                       as done here, we read in a pre-generated file... -->
                  <xsl:copy-of select="document($sidebar.tocfile.name)"/>

                  <!--  Original stylesheet did this...
                  <ul id="tree" class="filetree">
                    <xsl:apply-templates select="/*/*" mode="webhelptoc">
                      <xsl:with-param name="currentid" select="$currentid"/>
                    </xsl:apply-templates>
                  </ul>
                  -->
                </div>
              </div>
              <xsl:if test="$webhelp.include.search.tab != '0'">
                <div id="searchDiv">
                  <div id="search">
                    <form onsubmit="Verifie(searchForm);return false"
                      name="searchForm" class="searchForm">
                      <div>
                        <input id="textToSearch" name="textToSearch"
                               type="search" placeholder="Search"
                               class="searchText" tabindex="1"/>
                        <xsl:text disable-output-escaping="yes"> <![CDATA[&nbsp;]]> </xsl:text>
                        <input onclick="Verifie(searchForm)" type="button"
                               class="searchButton"
                               value="Go" id="doSearch" tabindex="1"/>
                      </div>
                    </form>
                  </div>
                  <div id="searchResults">
                    <center> </center>
                  </div>
                  <p class="searchHighlight">
                    <a href="#" onclick="toggleHighlight()">Search Highlighter (On/Off)</a>
                  </p>
                </div>
              </xsl:if>  <!-- if search-tab is included -->

              <xsl:call-template name="user.webhelp.tabs.content"/>
            </div>
          </div>
        </div>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>


  <!-- Write HTML <hr/> tags as explicit text; otherwise, you get <hr> -->
  <xsl:template name="set.titlepage.separator">
    <xsl:text disable-output-escaping="yes">&lt;hr/&gt;</xsl:text>
  </xsl:template>
  <xsl:template name="book.titlepage.separator">
    <xsl:text disable-output-escaping="yes">&lt;hr/&gt;</xsl:text>
  </xsl:template>


  <!-- We wanted to override the "javascript-not-enabled" message;
       our users aren't using this to "enjoy features of the site" -->
  <xsl:param name="local.l10n.xml" select="document('')"/>
  <l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0";>
    <l:l10n language="en">
      <l:context name="webhelp">
        <l:template name="txt_browser_not_supported" 
                    text="To use the Table of Contents and Search features, please enable JavaScript."/>
      </l:context>
    </l:l10n>
  </l:i18n>

  <!-- ==================================================================== -->
</xsl:stylesheet>
<?xml version='1.0'?>
<xsl:stylesheet
       xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
       xmlns:exsl="http://exslt.org/common";
       xmlns:ng="http://docbook.org/docbook-ng";
       xmlns:db="http://docbook.org/ns/docbook";
       version="1.0"
       xmlns="http://www.w3.org/1999/xhtml";
       exclude-result-prefixes="exsl ng db">

  <!-- This stylesheet is used to create a "table-of-contents" list for
       use in the webhelp sidebar. In the original stylesheets, this
       TOC is re-created for every webhelp HTML file generated so that
       an attribute can be put on the list item representing the current
       file, to act as a "you are here" indicator. This allows the sidebar
       TOC to highlight the item you select on the TOC. However, the
       creation of the sidebar TOC this way drove the processing time for
       the Admin helpset from about 2 minutes (for the vanilla HTML that
       was archived in a CHM file) to about over an hour. (The more finely
       you chunk the files, the worse it gets, quickly.)

       This was deemed unacceptable for the benefit of highlighting
       the TOC. So we excerpted out the template that generated the sidebar TOC
       into this stylesheet, modified it so it doesn't insert a "you are here"
       attribute, and ran this stylesheet separately, to create one
       file that contained the sidebar TOC.

       The main webhelp stylesheets were then modified to read this file
       in rather than calling the template that generates the TOC each time.

       We have a Perl script that runs over the generated HTML webhelp files,
       and it was trivial to use that script to identify the sidebar TOC
       entry corresponding to the file being processed, and to reinsert
       the 'id="webhelp-currentid" attribute into it as a post-processing step.
       This restored the highlighting function without the cost of doing it
       via the per-page XSLT.
   -->


  <!-- This is used simply to make the project and product stylesheets
       independently relocatable. This stylesheet doesn't need anything
       else from "webhelp", so we go right to xhtml/chunk.xsl (which is
       what webhelp imports).  The result should be something like this:
       <xsl:import href="c:/doc-stuff/docbook_xsl/docbook-xsl-1.78.1/xhtml/chunk.xsl"/>
  -->
  <xsl:import href="@REDIRECT-DIR@/xhtml/chunk.xsl"/>

  <!-- Import the shared project-specific stylesheet (used by
       mt-webhelptoc.xsl and mt-webhelp.xsl.) -->
  <xsl:import href="mt-webhelp-ids.xsl"/>


  <!-- /////////////// Stylesheet parameters //////////////////////// -->

  <!-- Use the section numbers in the TOC items -->
  <xsl:param name="webhelp.autolabel" select="1"/>
  <xsl:param name="chapter.autolabel" select="1"/>
  <xsl:param name="section.autolabel" select="1"/>
  <xsl:param name="section.label.includes.component.label" select="1"/>

  <!-- ==================================================================== -->
  <!-- Driver template. This simply starts the processing, generating an
       HTML <ul> element and starting the transforms in the
       "sidebar-webhelptoc" mode. This mode exists only in this stylesheet.
       There is only one real template that supports this mode, 
       the TOC generator below, adapted from the DocBook XSL stylesheets.

       All this stylesheet does is generate an HTML file that will be
       spliced into the "webhelp" HTML files in the sidebar.
  -->
  <xsl:template match="/">
    <ul id="tree" class="filetree">
      <xsl:comment>Pre-generated sidebar TOC listing</xsl:comment>
      <xsl:apply-templates match="/" mode="sidebar-webhelptoc"/>
    </ul>
  </xsl:template>

  <!-- ==================================================================== -->
  <!-- Stolen largely from the DocBook webhelp-common.xsl file, but
       altered so that it does not insert an 'id="webhelp-currentid' attribute
       on the TOC entry for the file in which it is currently generating the           TOC. Instead, we use this to generate a single TOC file before
       generating the webhelp, and we simply splice that TOC in, rather than
       regenerating it for every page. (The webhelp-currentid is added
       back in during a Perl post-processing step run before the search indexing
       is done. -->
  <xsl:template
      match="book|part|reference|preface|chapter|bibliography|appendix|article|topic|glossary|section|simplesect|sect1|sect2|sect3|sect4|sect5|refentry|colophon|bibliodiv|index|setindex"
      mode="sidebar-webhelptoc">

    <xsl:variable name="title">
      <xsl:if test="$webhelp.autolabel=1">
        <xsl:variable name="label.markup">
          <xsl:apply-templates select="." mode="label.markup"/>
        </xsl:variable>
        <xsl:if test="normalize-space($label.markup)">
          <xsl:value-of select="concat($label.markup,$autotoc.label.separator)"/>
        </xsl:if>
      </xsl:if>
      <xsl:apply-templates select="." mode="titleabbrev.markup"/>
    </xsl:variable>

    <xsl:variable name="href">
      <xsl:choose>
        <xsl:when test="$manifest.in.base.dir != 0">
          <xsl:call-template name="href.target"/>
        </xsl:when>
        <xsl:otherwise>
          <xsl:call-template name="href.target.with.base.dir"/>
        </xsl:otherwise>
      </xsl:choose>
    </xsl:variable>

    <xsl:variable name="id" select="generate-id(.)"/>

    <xsl:if test="not(self::index) or
                  (self::index and not($generate.index = 0))">
      <li>
        <span class="file">
          <a href="{substring-after($href, $base.dir)}"  tabindex="1">
            <xsl:value-of select="$title"/>
          </a>
        </span>
        <xsl:if test="part|reference|preface|chapter|bibliography|appendix|article|topic|glossary|section|simplesect|sect1|sect2|sect3|sect4|sect5|refentry|colophon|bibliodiv">
          <ul>
            <xsl:apply-templates
                select="part|reference|preface|chapter|bibliography|appendix|article|topic|glossary|section|simplesect|sect1|sect2|sect3|sect4|sect5|refentry|colophon|bibliodiv"
                mode="sidebar-webhelptoc">
            </xsl:apply-templates>
          </ul>
        </xsl:if>
      </li>
    </xsl:if>
  </xsl:template>

  <!-- ==================================================================== -->
  <!-- These templates are simply to swallow the invalid content in the
       "helpset" wrapper documents. These "sets" xinclude a bunch of <book>
       documents (which are all valid), but the set wrappers are actually not.
       In addition to wrapping the books, these produce a "splash page" but
       have a structure like this (which is invalid DocBook):
        <set>
          <title>...</title>
          <informaltable>..</informaltable></set>

       Because it is actually invalid, this stylesheet doesn't catch it,
       so the title and table content leaks into the sidebar TOC: 
       <ul>invalid set content<li><p>...</p></li>
         <li><p>...</p></li>
         <li><p>...</p></li>
         ....
       </ul>
       These trivial templates simply consume that content so it doesn't
       leak out to the TOC list.
  -->
  <xsl:template match="set/title" mode="sidebar-webhelptoc">
  </xsl:template>

  <xsl:template match="set/informaltable" mode="sidebar-webhelptoc">
  </xsl:template>
</xsl:stylesheet>
<?xml version='1.0'?>
<xsl:stylesheet
       xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
       xmlns:exsl="http://exslt.org/common";
       xmlns:ng="http://docbook.org/docbook-ng";
       xmlns:db="http://docbook.org/ns/docbook";
       version="1.0" xmlns="http://www.w3.org/1999/xhtml";
              exclude-result-prefixes="exsl ng db">

  <!-- This stylesheet is imported by mt-webhelp.xsl and mt-webhelptoc.xsl.
       It is used to make sure that the IDs generated when running either
       of those stylesheets will match. This is needed because we generate
       the sidebar TOC in one pass, and the HTML files that use the sidebar TOC
       in another. -->

  <!-- === PARAMETERS ================================================= -->
  <!-- Tell the stylesheets to generate the same ids each for each
       run (unless the doc structure has changed). We need this so that
       the IDs in our pre-generated sidebar TOC match those in the
       per-page HTML -->
  <xsl:param name="generate.consistent.ids" select="1"/>


  <!-- === TEMPLATES ================================================== -->
  <!-- This overrides the DocBook XSL object.id template in "common/common.xsl"

       It's overridden to change the behavior of the "generate-consistent-ids"
       case. By default, it generates ids with values like this:
       "id-4.3.11.3.6". For some reason (probably to do with some JavaScript
       somewhere), this causes a problem when trying to navigate using the
       Sidebar toc from some "distant" page (e.g., "bk01.html") to a nested
       link (e.g, "bk02ch04s02#id-4.2.11.3.6"). The sidebar vanishes and
       can't be brought back. However, changing the form of the generated
       ids to "id-4-3-11-3-6" seems to solve the problem.

       Note: Any explicitly provided IDs with "." in them will also exhibit
       the vanishing-sidebar problem.
 -->
  <xsl:template name="object.id">
    <xsl:param name="object" select="."/>
    <xsl:choose>
      <xsl:when test="$object/@id">
        <xsl:value-of select="$object/@id"/>
      </xsl:when>
      <xsl:when test="$object/@xml:id">
        <xsl:value-of select="$object/@xml:id"/>
      </xsl:when>
      <xsl:when test="$generate.consistent.ids != 0">
        <!-- Make $object the current node -->
        <xsl:for-each select="$object">

          <!-- "generated-label" will have a value like "4.3.11.3.4" -->
          <xsl:variable name="generatedlabel">
            <xsl:number level="multiple" count="*"/>
          </xsl:variable>

          <!-- "munged-label" will have a value like "4-3-11-3-4" -->
          <xsl:variable name="mungedlabel"
                        select="translate($generatedlabel, '.', '-')"/>

          <!-- The value of the id attribute will be "id-4-3-11-2-4" -->
          <xsl:text>id-</xsl:text>
          <xsl:value-of select="$mungedlabel"/>
        </xsl:for-each>
      </xsl:when>
      <xsl:otherwise>
        <xsl:value-of select="generate-id($object)"/>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>

</xsl:stylesheet>

Attachment: mt-webhelp.post-process-html.pl
Description: Binary data

Attachment: webhelp-readme-screenshot.png
Description: PNG image



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]